Booking Shifts
Use the Instawork Partner MCP server to book shifts on behalf of business partners using natural language.
For connection and authentication setup, see setup.md.
Available Tools
| Tool | Description |
|---|---|
searchCompanyLocations | Search for company locations, optionally filtered by a search query |
getPositions | Get a list of all available positions |
getPositionTemplates | Get all available position templates for a company |
getPositionTemplateDetails | Get the details of a position template |
getDefaultPositionTemplateForPosition | Get the default position template for a position |
getInstructionsOptions | Get available attire, grooming, and requirements options for a position |
getBreakLength | Get applicable break rules for a given state and shift length |
getPaymentOptions | Get available payment options for the partner, optionally filtered by location |
getOnsiteContacts | Get team members that can be added as onsite contacts |
getBookingPricing | Get initial, floor, recommended, and maximum bill rates for a booking |
getBookingTemplates | Get booking templates available for rebooking, filtered by location and/or position |
getBookingTemplateDetailsForRebooking | Get pre-filled booking data from a booking template |
getShiftgroupDetailsForRebooking | Get pre-filled booking data from a previous shift group |
searchShiftgroups | Search for shift groups by location, position, timeframe, and date range |
searchRosteredPros | Search for rostered professionals by location, name, or position |
createDraftBooking | Create a draft booking with positions, shifts, pricing, and roster details |
createBooking | Create and confirm a booking with positions, shifts, pricing, payment, and roster details |
Booking Workflow
Use this checklist for a new booking (one position, one schedule at a time):
- [ ] 1. Confirm location — searchCompanyLocations
- [ ] 2. Confirm position — getPositions
- [ ] 3. Get position instructions — getPositionTemplates → getPositionTemplateDetails
(if no templates: getDefaultPositionTemplateForPosition)
- [ ] 4. Discuss attire / requirements if needed — getInstructionsOptions
- [ ] 5. Confirm onsite contact — getOnsiteContacts
- [ ] 6. Confirm staffing option (default: Smart assign)
- [ ] 7. Confirm shift date, start time, end time, headcount
- [ ] 8. Get break rules — getBreakLength
- [ ] 9. Get pricing — getBookingPricing → set bill rate to initial rate (unless overridden)
- [ ] 10. Confirm payment — getPaymentOptions (silent if only one; ask if two or more)
- [ ] 11. Present booking summary and wait for explicit confirmation
- [ ] 12. Create booking — createBooking (or createDraftBooking if payment is ambiguous)Rebooking from a template: use getBookingTemplates → getBookingTemplateDetailsForRebooking to pre-fill data, then resume from step 7.
Rebooking from a previous shift: use searchShiftgroups → getShiftgroupDetailsForRebooking to pre-fill data, then resume from step 7.
Booking Summary Template
Always present this before creating a booking and wait for explicit confirmation:
---
**Booking Summary**
- Location: [Location name]
- Position: [Position] (x[number] pros)
- Date: [Date]
- Time: [Start] – [End] ([Duration] hours)
- Break: [Length] minutes
- Rate/hour: $[Rate]
- Special requests: [Any requested pros or instructions]
---
Does this look correct? Reply 'confirm' to book or let me know what to change.Rules & Constraints
Limitations
- Only USA and Canada are supported. Do not attempt to book shifts in any other country.
- Long-term staffing and permanent positions are not supported. Explain this clearly if requested.
One at a Time
- Book one schedule or position at a time. Do not attempt to create multiple positions or schedules in a single booking flow.
Position and Instructions Setup
Critical: Attire, job duties, and on-site instructions directly affect shift outcomes. Do not post a shift until these fields are captured (see steps 3–4 of the workflow above).
Staffing Options
| Option | Behaviour |
|---|---|
| Smart assign | Prioritises requested pros → rostered pros → best market pros → all other pros. ML-driven to balance quality and fill rate. |
| Requested pros only | Only opens the shift to explicitly requested professionals. Look these up using searchRosteredPros. |
| New pros | Opens the shift to professionals who have not previously worked with this partner. |
Default to Smart assign unless the partner specifies otherwise.
Pricing
- Always set the bill rate to the initial rate returned by
getBookingPricing, unless the partner explicitly requests a different rate.
Payment Options
- If there is only one payment option, use it silently.
- If there are two or more, ask which they should use, eg.: *"I see a Visa card and a Mastercard — which one should I use?"*
- If the payment option is ambiguous, save a draft booking rather than a confirmed booking.
Shift Validation
Enforce the following before submitting. Explain any violation clearly:
- Shifts must start at least 30 minutes from the current time.
- Maximum shift duration is 12 hours.
- Shift end time must be after the start time.
- Unpaid break cannot exceed total shift duration.
- Minimum unpaid break must comply with legal requirements from
getBreakLength.
Error Handling
- Recover gracefully when tool calls fail, information is missing, or a request is unsupported.
- Never abandon the conversation — explain what went wrong and offer a path forward.
Other
- Do not display internal IDs like position_id or booking_id to the user during the conversation, reference everything by name.