Manage Roster MCP Tool Reference

Every tool the MCP server exposes, what it answers, and the arguments it takes.

What this does

Each tool below maps to one question a support lead actually asks. The model picks a tool by matching your phrasing against the descriptions, so asking in plain language ("who's off next week?") works better than trying to name the tool yourself.

Tools you have not been granted are not shown to your client at all — tools/list is filtered by your token's scopes. If a tool below is missing in your session, check the token's scopes in Settings → API & MCP.

Tool list

Tool	Type	What it does	Arguments
get_workspace_info	Read	Workspace name, timezone, active agent count, enabled feature modules, and your role.	None
list_agents	Read	The agents on the team with holiday group, off days and active status. Use it to resolve a name to an agent_id.	active_only
get_schedule	Read	Who is working when, over a date range. Contiguous hours are collapsed into blocks.	period, from, to, agent_id
find_coverage_gaps	Read	The hours where nobody (or too few people) is rostered. "Which slots are empty this week?"	period, from, to, min_agents
find_available_agents	Read	Who is free on a date — not rostered, not on leave. Agents on a public holiday are returned but flagged.	date, hour
list_leaves	Read	Leave overlapping a date range. "Who is on leave next week?"	period, from, to, status, agent_id
list_holidays	Read	Public holidays in a range, with the agents each one applies to.	period, from, to, group
list_ot_events	Read	Overtime events with status and submission counts.	status
get_ot_coverage	Read	Slot-by-slot OT coverage for one event, and which slots nobody claimed.	event_id
get_missed_reports	Read	Dates where a rostered agent did not submit a work report.	period, from, to, agent_id
assign_shift	Write	Assign an agent to a block of hours on one date.	agent_id, date, start_hour, end_hour, is_ot, notes
unassign_shift	Write	Remove an agent from a block of hours.	agent_id, date, start_hour, end_hour
create_leave	Write	File a leave request. Pending by default.	agent_id, type, start_date, end_date, notes, status
update_leave_status	Write	Approve or reject an existing leave request.	leave_id, status

Tools that are not always present

Write tools (assign_shift, unassign_shift, create_leave, update_leave_status) are hidden entirely on read-only connections.

Read tools are hidden when the token lacks the matching scope — list_leaves needs leaves:read, get_ot_coverage needs ot:read, and so on. See Connection scopes.

Arguments explained

period — a relative date range resolved on the server in your workspace timezone. Accepted values are today, yesterday, tomorrow, this_week, next_week, last_week, this_month, next_month. Defaults to this_week on most tools and this_month on list_holidays.

Prefer this over computing dates yourself. Models are unreliable at working out "next week" from today's date, and a wrong range produces a confident, wrong answer rather than an error.

from / to — explicit dates in YYYY-MM-DD format. When both are given they override period. Ranges longer than 366 days are truncated to 366.

agent_id — the numeric id of an agent, from list_agents. Ids are workspace-specific; never guess one. An id from another workspace is rejected.

active_only — true or false. Defaults to true, so inactive agents are excluded unless you ask for them.

min_agents — on find_coverage_gaps, the minimum number of agents on shift for an hour to count as covered. Defaults to 1. Set it to 2 to find hours with only single cover.

status — on list_leaves, one of pending, approved, rejected. On list_ot_events, one of draft, active, closed. On create_leave and update_leave_status, one of pending, approved, rejected. Omit to get everything.

group — on list_holidays, a holiday group code such as BD or PH. Holiday groups are per-agent, so one workspace can run several national calendars at once. Omit for all groups.

date — a single date in YYYY-MM-DD format.

hour — an integer 0–23. On find_available_agents, omit it to check the whole day.

start_hour / end_hour — the schedule is hour-granular. start_hour is 0–23 and end_hour is exclusive, 1–24. A 09:00–17:00 shift is start_hour: 9, end_hour: 17.

Overnight shifts

A shift crossing midnight must be written as two calls: one ending at hour 24 on the first date, and one starting at hour 0 on the next. A 22:00–06:00 shift is {date: "2026-09-08", start_hour: 22, end_hour: 24} followed by {date: "2026-09-09", start_hour: 0, end_hour: 6}.

type — on create_leave, one of annual, sick, casual, maternity. Any other value is rejected.

is_ot — true or false. Marks the assigned hours as overtime. Defaults to false.

notes — free text on a shift or leave request. Redacted in the activity log.

event_id / leave_id — numeric ids from list_ot_events and list_leaves respectively.

How results come back

Every tool returns JSON in a text content block, and the identical value as structuredContent for clients that read it. The two never disagree.

structuredContent is always a JSON object, never a bare array — that is what the MCP spec requires, and clients reject the whole response otherwise. Tools that return a collection wrap it under a named key alongside the resolved query, so you can see what was actually asked:

{
  "from": "2026-09-07",
  "to": "2026-10-07",
  "group": "PH",
  "holidays": [ … ],
  "count": 3
}

Tool	Collection key
list_agents	agents
list_leaves	leaves
list_holidays	holidays
list_ot_events	ot_events
find_available_agents	available_agents
get_missed_reports	missed
get_schedule	days
find_coverage_gaps	gaps

Each also carries a count or equivalent total, so you can check whether a result is empty without walking the array.

find_coverage_gaps returns contiguous ranges rather than individual hours, so a six-hour hole reads as one gap and not six, along with an overall coverage_percent.

get_schedule collapses consecutive hours for the same agent into blocks, so an agent rostered 22:00–06:00 comes back as one entry rather than eight.

When a tool refuses

Write tools validate against the roster's own rules before changing anything, and refuse with an explanation rather than a generic error:

• Agent is on approved leave — assign_shift refuses and names the leave type and dates
• Agent is already rostered in those hours — refuses and lists the clashing hours
• Overlapping leave already exists — create_leave refuses and names the existing request
• Invalid hours — refuses and explains the overnight two-call rule

These come back as tool errors (isError: true) with a readable message, not protocol errors, so the model can read the reason and pick a different agent instead of retrying blindly.

create_leave warns rather than refuses when the agent is already rostered during the requested dates — that is a real situation a human needs to resolve, not something to block.

Security notes

• Every tool call is written to the activity log with the token, actor, parameters, status and duration. Free-text fields (notes, leave reasons, report bodies) are redacted.
• Tools are scoped to the token's single workspace. There is no tool that crosses workspaces.
• There is no tool that deletes agents, workspaces, historical schedules or reports. The most destructive available action is unassigning shifts.
• The server instructs models to confirm with you before any write. Treat that as a courtesy, not a control — the scope is the control.

FAQ

Why does the model not use a tool I know exists? Usually a scope issue — check tools/list output. If it is present but unused, phrase the request closer to the tool's description ("find coverage gaps next week" rather than "check the rota").

Can I add my own tools? Not yet. The tool set is fixed in v1.

Does get_missed_reports count days an agent was not working? No. It only counts dates where the agent was actually rostered, which is what makes the number meaningful.

What timezone are dates in? Your workspace timezone, set in workspace settings. period values are resolved against it server-side.

Related

• MCP server setup — connecting a client
• Connection scopes — what each scope permits
• REST API reference — the same data over plain HTTP