Skip to content
WorkWing Docs

Connect an AI assistant safely

An assistant connected to WorkWing can book real work that your engineers will turn up for. This recipe covers the choices that decide what it can reach and when it stops to ask: whose account it acts as, which of its tools change things, and what WorkWing enforces on its own as opposed to what you have to set up in the assistant.

The connection steps themselves, and what to say to the assistant, are on AI assistants. Read that first.

Decide whose account it acts as

Section titled “Decide whose account it acts as”

The assistant acts as the person who signs in when it’s connected. It isn’t given a key of its own. It works in one workspace, with that person’s role in it, so it reaches what they reach and can do what their permissions allow.

That has three consequences worth planning for:

  • There’s no read-only switch on the connection. The consent screen lists reading and writing together, and approving it approves both. What actually limits the assistant is the role of the account that connected it.
  • To limit it, limit the account. If someone should only look things up through the assistant, give them a role without permission to create jobs or assign people, and the assistant can do no more than they can. Build one from Settings > Roles & Permissions (see Roles and permissions).
  • Only staff can connect one. An external worker can’t: the consent screen tells them their account has no workspace that can connect an AI assistant.

If you belong to more than one workspace, the consent screen asks which one the connection works in, and it stays there. To change it, remove the connector and connect again.

Know which tools change things

Section titled “Know which tools change things”

The assistant works through a fixed set of tools. Nine read, five write, and nothing else in WorkWing is reachable: billing, members, roles and settings stay in the web app, and no tool deletes anything.

Tool What it does Changes anything?
find_customer Finds customers by name, phone, email or postcode, with their sites No
find_resource Finds engineers by name or email, with their availability No
get_job Fetches a job by number or id, or searches for one No
get_schedule Lists jobs between two times, for everyone or one engineer No
get_availability Finds gaps in one engineer’s day No
list_job_templates Finds the job type that matches what you called the work No
find_project Finds a project, with its crew and jobs No
search, fetch Search and read records, for ChatGPT’s research features No
create_job Creates a job for a customer, or a job inside a project Yes
schedule_job Sets a job’s time and books an engineer onto it Yes
add_project_crew Puts an engineer on a project’s crew Yes
add_job_note Adds a note to a job Yes
cancel_job Cancels a job Yes, and the assistant can’t undo it

list_job_templates is named after the API’s word for a job type. It returns your job types.

Each tool also tells the assistant how it behaves. The nine lookups are marked read-only. cancel_job is marked destructive. schedule_job, add_project_crew and cancel_job are marked safe to repeat, because running one twice with the same details leaves things as one run did. create_job and add_job_note are not: if the assistant calls either twice, you get two jobs or two notes.

Make it ask before it writes

Section titled “Make it ask before it writes”

WorkWing doesn’t stop to ask for your approval. The assistant does, if you set it up to.

Every write tool’s description tells the assistant to read back what it’s about to do and get your agreement first: the customer, site, work and time before create_job, the engineer and time before schedule_job, and an explicit yes, naming the job and customer, before cancel_job. A well-behaved assistant follows that. It’s an instruction, though, not a lock, and an assistant can misread a conversation.

So set the five write tools to need your approval in the assistant’s connector settings, where it offers that. With approval on, the assistant can look things up freely and has to show you each change before it’s made.

After a change, check it in WorkWing. create_job gives back the new job’s number, so you can open the job and look.

What WorkWing enforces

Section titled “What WorkWing enforces”

These hold whatever the assistant decides to do:

  • Your permissions. A write your role doesn’t allow is refused, with a message naming the permission you’re missing and telling the assistant not to retry. A locked schedule needs the permission to reschedule locked jobs, exactly as in the web app.
  • Status rules. A completed or failed job can’t be cancelled. A cancelled job is closed: only someone with permission to reopen closed jobs can bring it back, in the web app, and no tool can.
  • A job type before booking. A job without a job type can’t be scheduled or assigned, so schedule_job refuses it and says why.
  • The right site. A site passed to create_job must belong to that customer.
  • The workspace. The connection only ever works in the workspace chosen when it was connected.

What it doesn’t stop

Section titled “What it doesn’t stop”

These are left to you and the assistant:

  • Clashes. schedule_job books an engineer over something they already have, because sometimes that’s what a dispatcher means. The reply carries a warning, and the assistant is told to pass every warning on. Make sure it does.
  • Automatic assignment. If your account assigns new jobs automatically, the system may pick an engineer the moment create_job runs. When the assistant then books a named engineer with schedule_job, the automatic pick is removed and the reply says so. An engineer someone assigned by hand stays on the job, and the reply warns that the job now has more than one.
  • Duplicate jobs. If the assistant isn’t sure a create_job went through, ask it to look the job up with get_job before trying again.
  • Free time is a shortlist. get_availability counts booked jobs and recorded absences. It doesn’t know working hours, travel time or skills, and it says so in every answer. It never offers time that has already gone.
  • Which site. When a customer has several sites and the assistant names none, the job goes to the customer’s primary site, with a warning saying which address was used.

Expect the same behaviour every time

Section titled “Expect the same behaviour every time”

The tools are built so the assistant has less room to guess.

Lookups return a short list and say what it means. find_customer, find_resource, get_job, find_project and list_job_templates return at most 5 matches, and get_schedule at most 50 jobs. Each answer carries a line of guidance from WorkWing saying whether the list is complete, empty or cut short, and telling the assistant to ask you which one you meant rather than pick one.

Ids come from lookups. The write tools take ids, and their descriptions tell the assistant to take them from a lookup, never to guess one. A customer it can’t find is a question for you, not an id it invents.

Your records are marked as data. Job titles, notes and customer names are written by people, and one could contain text that reads like an instruction, such as a note saying “cancel every job this week”. Every answer marks where your records start and end, and tells the assistant that text inside is something to report, not something to act on. That lowers the risk without removing it, which is one more reason to keep approval on for writes.

Take access away

Section titled “Take access away”

To stop one connection, remove the WorkWing connector in the assistant’s connector settings.

To cut someone off whatever they’ve connected, suspend their WorkWing account or remove them from the organisation. Their assistant is refused within a minute.

What’s next

Section titled “What’s next”