> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent tools

> Use Google Workspace agent tools in Ravenna rules to manage users and groups, reset MFA and passwords, manage email aliases, and transfer files at offboarding.

Google Workspace provides AI agent tools for user lifecycle, group, and mailbox operations. Reference these tools in agent rules (Natural language instructions defining agent behavior) using @ mentions so your agent can create accounts, adjust group access, reset credentials, and move a departing user's files without escalating to IT.

These tools use the same Google Workspace integration as the [workflow actions](https://docs.ravenna.ai/integrations/google-workspace/workflows.md), but their inputs are built for an agent and don't always match the workflow action of the same purpose.

***

## Manage users

> [accordion] Create user
>
> Creates a new Google Workspace user with a randomly generated password. The password is not returned. Give the user access by running `@Reset Google MFA/Password` with the `password` scope and `generatePassword` set to `true` once they can receive a Slack DM, or send them through Google's own recovery flow.
>
> **Tool name:** `@Create Google User`
>
> **Input fields:**
>
> * `emailUsername` (required) - the username portion of the new primary email, or the full address.
> * `firstName`, `lastName` (required) - the user's name.
> * `domain` - the domain for the primary email. Defaults to the primary domain on your Google Workspace integration. Set it to provision on a secondary verified domain.
> * `secondaryEmail`, `recoveryEmail`, `recoveryPhone` - contact and recovery details.
> * `orgUnitPath` - the organizational unit, for example `/Engineering`. Defaults to `/`.
> * `department`, `jobTitle`, `managerEmail` - profile details.
>
> **Output data:**
>
> * `email` - the new primary email address.
> * `userId` - the user's Ravenna ID.
> * `googleUserId` - the user's Google ID.
>
> **Common use cases:**
>
> * Create accounts for new hires from an onboarding request
> * Provision contractor accounts in a dedicated organizational unit
> * Create users on a secondary domain for a brand or region
>
> **Example rule:**
>
> When an onboarding request comes in, use @Check Google Email Availability on firstname.lastname, then use @Create Google User with the new hire's name, department, job title, and manager. Reply with the new email address, then offer to send the hire a temporary password with @Reset Google MFA/Password.
>
> When an onboarding request comes in, use @Check Google Email
> Availability on firstname.lastname, then use @Create Google User
> with the new hire's name, department, job title, and manager. Reply
> with the new email address, then offer to send the hire a temporary
> password with @Reset Google MFA/Password.

> [accordion] Reset MFA or password
>
> Resets multi-factor authentication, the password, or both, in one call. A password reset always requires the user to choose a new password at next sign-in. By default the tool also generates a temporary password and delivers it to the user in a private Slack DM, so it never appears in the ticket.
>
> **Tool name:** `@Reset Google MFA/Password`
>
> **Input fields:**
>
> * `userEmail` (required) - the user to reset.
> * `scope` (required) - `mfa`, `password`, or `both`.
> * `generatePassword` - defaults to `true` for password resets. Set it to `false` when the user cannot receive a Slack DM, so Google's own recovery flow takes over instead.
> * `signUserOut` - signs the user out of every active session.
>
> If the temporary password cannot be delivered privately, the tool tells the agent to rerun with `generatePassword` set to `false`.
>
> **Common use cases:**
>
> * Reset MFA for a user who lost or replaced their phone
> * Reset a forgotten password
> * Reset both and sign the user out after a suspected compromise
>
> **Example rule:**
>
> When someone is locked out of Google, use @Reset Google MFA/Password. Reset MFA only when they mention a new device, the password only when they forgot it, and both with signUserOut after a suspected compromise. Deliver any temporary password through a Slack DM, never in the ticket.
>
> When someone is locked out of Google, use @Reset Google
> MFA/Password. Reset MFA only when they mention a new device, the
> password only when they forgot it, and both with signUserOut after
> a suspected compromise. Deliver any temporary password through a
> Slack DM, never in the ticket.

> [accordion] Suspend user
>
> Suspends a Google Workspace user so they can no longer sign in to any Google service. The account and its data stay intact until you restore or delete it.
>
> **Tool name:** `@Suspend Google User`
>
> **Input fields:**
>
> * `userEmail` (required) - the user to suspend.
>
> **Common use cases:**
>
> * Lock an account at the end of an employee's last day
> * Disable a compromised account during a security incident
> * Lock an account during extended leave
>
> **Example rule:**
>
> When the security team reports a compromised Google account, use @Suspend Google User on it immediately, then confirm in the reply that the account is suspended and tag the security team.
>
> When the security team reports a compromised Google account, use
> @Suspend Google User on it immediately, then confirm in the reply
> that the account is suspended and tag the security team.

> [accordion] Restore user
>
> Unsuspends a previously suspended user, restoring access to every Google service.
>
> **Tool name:** `@Restore Google User`
>
> **Input fields:**
>
> * `userEmail` (required) - the suspended user to restore.
>
> **Common use cases:**
>
> * Restore access when someone returns from leave
> * Reactivate an account after a security review clears it
> * Re-enable a returning contractor
>
> **Example rule:**
>
> When a manager confirms someone has returned from leave, use @Restore Google User on their account and tell them they can sign in again.
>
> When a manager confirms someone has returned from leave, use
> @Restore Google User on their account and tell them they can sign
> in again.

> [!NOTE]
>
> Any signed-in member can trigger these tools, including for another person. To limit who can act on someone else's account or group, set **Requires approval** on the tool in the rule, or scope the rule to the people who should use it.

***

## Manage email addresses

> [accordion] Check email availability
>
> Checks whether an email address is already in use as a primary email or alias in Google Workspace. Run it before creating a user or alias so the agent can offer a different address instead of failing on a conflict.
>
> **Tool name:** `@Check Google Email Availability`
>
> **Input fields:**
>
> * `email` (required) - the address to check.
>
> **Output data:**
>
> * `isAvailable` - `true` when the address is free.
> * `reason` - why the address is taken, when it is unavailable.
>
> **Common use cases:**
>
> * Confirm a new hire's address is free before creating their account
> * Check that a requested alias is not already claimed
> * Suggest an alternative address when the first choice is taken
>
> **Example rule:**
>
> Before creating a Google account or email alias, use @Check Google Email Availability on the requested address. If it is taken, tell the requester why and suggest an alternative, such as adding a middle initial.
>
> Before creating a Google account or email alias, use @Check Google
> Email Availability on the requested address. If it is taken, tell
> the requester why and suggest an alternative, such as adding a
> middle initial.

> [accordion] Create email alias
>
> Adds an email alias to an existing user so mail sent to the alias delivers to the same inbox.
>
> **Tool name:** `@Create Email Alias`
>
> **Input fields:**
>
> * `userEmail` (required) - the user who receives mail sent to the alias.
> * `aliasEmail` (required) - the alias to add. Pass the full address, or just the username and the domain is appended.
>
> **Common use cases:**
>
> * Add role-based addresses such as support@ or sales@ to one person
> * Add a brand-specific address for a customer-facing employee
> * Keep an old address working after a name change
>
> **Example rule:**
>
> When someone asks for an email alias, use @Check Google Email Availability on the alias first. If it is free, use @Create Email Alias to add it to their account and confirm the new address. If it is taken, explain why and ask for a different alias.
>
> When someone asks for an email alias, use @Check Google Email
> Availability on the alias first. If it is free, use @Create Email
> Alias to add it to their account and confirm the new address. If it
> is taken, explain why and ask for a different alias.

***

## Manage groups

Every tool that acts on an existing group identifies it by the group's `name` or `email`, not a member's email.

> [accordion] List groups
>
> Lists the Google Groups in your workspace. Use it to find the exact name or email of a group before acting on it.
>
> **Tool name:** `@List Google Groups`
>
> **Input fields:**
>
> * `filter` - text matched against group names and emails.
>
> **Output data:**
>
> * `groups` - each group's `name`, `email`, and `description`.
> * `totalCount` - how many groups matched.
> * `truncated` - `true` when more than 50 groups matched and only the first 50 came back. Pass a narrower `filter` to see the rest.
>
> **Common use cases:**
>
> * Resolve a loosely named group ("the design list") to its exact address
> * Show a requester which groups they can ask to join
> * Audit groups that match a naming convention
>
> **Example rule:**
>
> When someone asks to join a Google group but does not give its exact address, use @List Google Groups with a filter from their request. If more than one group matches, ask which one they mean before making any change.
>
> When someone asks to join a Google group but does not give its
> exact address, use @List Google Groups with a filter from their
> request. If more than one group matches, ask which one they mean
> before making any change.

> [accordion] Get group info
>
> Looks up one Google Group by its name or email and returns its details. When the agent only has part of a name, have it call `@List Google Groups` first.
>
> **Tool name:** `@Get Google Group Info`
>
> **Input fields:**
>
> * `name` or `email` - the group to look up.
>
> **Output data:**
>
> * `found` - `false` when no group matches.
> * `name`, `email`, `description` - the group's details.
>
> **Common use cases:**
>
> * Confirm a group exists before changing it
> * Explain what a group is for from its description
> * Check a group's address before sharing it
>
> **Example rule:**
>
> When someone asks what a Google group is for, use @Get Google Group Info and reply with its description and email address. If the group is not found, use @List Google Groups to suggest close matches.
>
> When someone asks what a Google group is for, use @Get Google Group
> Info and reply with its description and email address. If the group
> is not found, use @List Google Groups to suggest close matches.

> [accordion] Create group
>
> Creates a Google Group, and can assign owners and managers and set who can join and post in the same call. Only `name` is required.
>
> **Tool name:** `@Create Google Group`
>
> **Input fields:**
>
> * `name` (required) - the group's display name.
> * `description` - what the group is for.
> * `email` - the group's address. Derived from the name and your integration's domain when omitted.
> * `ownerEmail` - one user to add as owner. Defaults to the person making the request.
> * `managerEmails` - users to add as managers. Managers can moderate members and messages but cannot delete the group.
> * `requesterRole` - `owner`, `manager`, or `none`. Sets the requester's own role. Defaults to `owner` when `ownerEmail` is omitted, and to `none` when it names someone else.
> * `accessLevel` - who can join, view, and post:
>   * `public` - anyone on the internet. Also requires external members.
>   * `open` - anyone in your domain.
>   * `restricted` - invite only, members can view and post.
>   * `closed` - invite only, only managers can view and post.
> * `allowExternalMembers` - lets people outside your domain be members without making the group public.
> * `enableConversationHistory` - archives messages so they can be read later. Off by default.
>
> Owners and managers must be Ravenna users. Anyone named as both owner and manager is added as owner only.
>
> **Output data:**
>
> * `groupName`, `groupEmail`, `groupId` - the new group's details.
>
> **Common use cases:**
>
> * Create a group for a new team or project with its lead as owner
> * Set up an invite-only group for a sensitive project
> * Create a group that accepts external collaborators
>
> **Example rule:**
>
> When someone requests a new Google group, ask for its name, purpose, and who should own it. Use @Create Google Group with accessLevel restricted unless they ask for something broader, then reply with the group's email address.
>
> When someone requests a new Google group, ask for its name, purpose,
> and who should own it. Use @Create Google Group with accessLevel
> restricted unless they ask for something broader, then reply with
> the group's email address.

> [accordion] Update group
>
> Changes one attribute of an existing Google Group per call. To make several changes, the agent calls the tool once for each.
>
> **Tool name:** `@Update Google Group`
>
> **Input fields:**
>
> * `name` or `email` - the group to update.
> * `change` (required) - which attribute to change, paired with one more field:
>
> | `change` | Field to pass | Effect |
> | - | - | - |
> | `set_owner` | `ownerEmail` | Adds the user as an owner. Existing owners stay. |
> | `add_manager` | `managerEmail` | Adds the user as a manager. Existing managers stay. |
> | `set_access_level` | `accessLevel` | Sets `public`, `open`, `restricted`, or `closed`, with the same meanings as `@Create Google Group`. |
> | `set_external_members` | `allowExternalMembers` | Allows or blocks members outside your domain without changing the access level. |
>
> This tool covers ownership, management, and access. For posting permissions, moderation, and other group settings, use the [Update Group workflow action](https://docs.ravenna.ai/integrations/google-workspace/workflows.md).
>
> **Common use cases:**
>
> * Add a new owner when a group's lead changes roles
> * Add a manager to help moderate a busy group
> * Open a group to your whole domain, or lock it down to invite only
> * Allow external members for a partner collaboration
>
> **Example rule:**
>
> When a group owner asks to change who can join their Google group, confirm which access level they mean (open, restricted, or closed), then use @Update Google Group with change set\_access\_level. Confirm the new setting in the reply.
>
> When a group owner asks to change who can join their Google group,
> confirm which access level they mean (open, restricted, or closed),
> then use @Update Google Group with change set\_access\_level. Confirm
> the new setting in the reply.

> [accordion] Check group membership
>
> Checks whether a user belongs to a Google Group, and in what role.
>
> **Tool name:** `@Check Google Group Membership`
>
> **Input fields:**
>
> * `userEmail` (required) - the user to check.
> * `name` or `email` - the group.
>
> **Output data:**
>
> * `isMember` - `true` when the user is in the group.
> * `role` - `OWNER`, `MANAGER`, or `MEMBER` when the user is in the group.
>
> **Common use cases:**
>
> * Explain why someone is or is not receiving a group's email
> * Confirm membership before adding or removing someone
> * Check who has owner rights before approving a group change
>
> **Example rule:**
>
> When someone says they are not receiving emails sent to a Google group, use @Check Google Group Membership for them and that group. If they are not a member, offer to add them with @Add Google Group Member.
>
> When someone says they are not receiving emails sent to a Google
> group, use @Check Google Group Membership for them and that group.
> If they are not a member, offer to add them with @Add Google Group
> Member.

> [accordion] Add group member
>
> Adds one user to a Google Group. The address does not need to belong to a Ravenna user, so you can add contractors and other external collaborators. To add several people, the agent calls the tool once per person.
>
> **Tool name:** `@Add Google Group Member`
>
> **Input fields:**
>
> * `userEmail` (required) - the address to add.
> * `name` or `email` - the group.
>
> If the user is already a member, Google rejects the request and the agent relays the error.
>
> **Common use cases:**
>
> * Add a new hire to their team's groups
> * Grant access to a shared drive or calendar controlled by a group
> * Add an external contractor to a project group
>
> **Example rule:**
>
> When someone asks to join a Google group, use @Add Google Group Member to add them and confirm in the reply. If the group is ambiguous, use @List Google Groups first and ask which one they mean.
>
> When someone asks to join a Google group, use @Add Google Group
> Member to add them and confirm in the reply. If the group is
> ambiguous, use @List Google Groups first and ask which one they
> mean.

> [accordion] Remove group member
>
> Removes one user from a Google Group. The user must be a Ravenna user. To remove several people, the agent calls the tool once per person.
>
> **Tool name:** `@Remove Google Group Member`
>
> **Input fields:**
>
> * `userEmail` (required) - the user to remove.
> * `name` or `email` - the group.
>
> If the user is not a member, Google rejects the request and the agent relays the error.
>
> **Common use cases:**
>
> * Remove someone from a team's groups when they change roles
> * Revoke access controlled by a group during offboarding
> * Honor a request to leave a mailing list
>
> **Example rule:**
>
> When someone asks to leave a Google group, use @Remove Google Group Member to remove them and confirm in the reply. To remove someone else, first use @Check Google Group Membership to confirm the requester is an owner or manager of that group.
>
> When someone asks to leave a Google group, use @Remove Google Group
> Member to remove them and confirm in the reply. To remove someone
> else, first use @Check Google Group Membership to confirm the
> requester is an owner or manager of that group.

> [accordion] Delete group
>
> Deletes a Google Group.
>
> > [!WARNING]
> >
> > Deleting a group removes every member's membership immediately and cannot be undone. Confirm with the requester before running this tool.
>
> **Tool name:** `@Delete Google Group`
>
> **Input fields:**
>
> * `name` or `email` - the group to delete.
>
> **Common use cases:**
>
> * Remove a group after a project ends
> * Clean up unused distribution lists
> * Delete a team's groups when the team is dissolved
>
> **Example rule:**
>
> When a group owner asks to delete a Google group, use @Get Google Group Info to confirm the group and repeat its name and email back to them. Only run @Delete Google Group after they confirm.
>
> When a group owner asks to delete a Google group, use @Get Google
> Group Info to confirm the group and repeat its name and email back
> to them. Only run @Delete Google Group after they confirm.

***

## Offboard users

> [accordion] Transfer user files
>
> Starts an asynchronous transfer of a user's Google Drive and Calendar data to another user. Google processes the transfer in the background and Ravenna returns a transfer ID for tracking. Use it before suspending or deleting an account so nothing is lost.
>
> > [!NOTE]
> >
> > This tool needs the **Enable User Data Transfer** setting on your Google Workspace integration, plus the `admin.datatransfer` scope on domain-wide delegation. See the [setup guide](https://docs.ravenna.ai/integrations/google-workspace/setup.md#enable-data-transfer-optional).
>
> **Tool name:** `@Transfer Google User Files`
>
> **Input fields:**
>
> * `sourceUserEmail`, `destinationUserEmail` (required) - who the data moves from and to.
> * `driveTransferScope` - `ALL` (default), `PRIVATE`, `SHARED`, or `NONE`.
> * `transferCalendarEvents` - defaults to `true`.
> * `releaseCalendarResources` - releases rooms and equipment on future events. Only applies when calendar transfer is enabled.
>
> At least one of Drive or Calendar must be transferred.
>
> **Output data:**
>
> * `transferId` - the Google Data Transfer ID for tracking.
>
> **Common use cases:**
>
> * Hand a departing employee's files to their manager during offboarding
> * Move project files to a new owner when someone changes teams
> * Transfer calendar ownership when responsibilities change
>
> **Example rule:**
>
> When a manager reports someone is leaving, ask for the source and destination user, then run @Transfer Google User Files with driveTransferScope ALL and transferCalendarEvents true. After the transfer ID comes back, run @Suspend Google User on the source account and confirm both steps in the reply.
>
> When a manager reports someone is leaving, ask for the source and
> destination user, then run @Transfer Google User Files with
> driveTransferScope ALL and transferCalendarEvents true. After the
> transfer ID comes back, run @Suspend Google User on the source
> account and confirm both steps in the reply.

A tool with no execution policy set runs without asking. When Copilot drafts a rule, it suggests **Requires confirmation** for write tools and **Requires approval** for delete tools, and you can change either per rule. See [tool execution policies](https://docs.ravenna.ai/documentation/automate/agents/configure.md#tool-execution-policies).

***

## Setup

**1. Install Google Workspace integration**

Follow the [Google Workspace setup guide](https://docs.ravenna.ai/integrations/google-workspace/setup.md) to connect your Google Workspace to Ravenna.

**2. Enable data transfer (optional)**

Turn on **Enable User Data Transfer** and grant the `admin.datatransfer` scope on domain-wide delegation before writing rules that use `@Transfer Google User Files`.

**3. Configure agent**

Open your agent's settings and add the Google Workspace tools you want it to use under **Tools**. An admin has to attach each tool before an agent or rule can call it.

**4. Create rules**

Write rules (Natural language instructions defining agent behavior) that reference Google Workspace tools using @ mentions.

**5. Test tools**

Test your rules on a real request to verify the tools work as expected.

***

## Best practices

* **Check before you create.** Pair `@Check Google Email Availability` with `@Create Google User` and `@Create Email Alias` so the agent catches conflicts before it writes.
* **Find the group first.** When a request names a group loosely, have the agent run `@List Google Groups` with a `filter` before it adds, removes, or updates anything.
* **Transfer, then suspend.** Run `@Transfer Google User Files` before `@Suspend Google User` during offboarding. Suspended users cannot start a transfer.
* **Deliver temporary passwords privately.** When you use `@Reset Google MFA/Password` in `generatePassword` mode, have the rule send the password through a private Slack DM instead of putting it in the ticket.
* **Gate the destructive tools.** Put `@Delete Google Group`, `@Remove Google Group Member`, `@Suspend Google User`, and any reset in `generatePassword` mode behind **Requires approval** in rules an agent can reach on its own.

Learn more about [configuring agents](https://docs.ravenna.ai/documentation/automate/agents/configure.md) and [Google Workspace workflow actions](https://docs.ravenna.ai/integrations/google-workspace/workflows.md)


## Related topics

- [Agent tools](https://docs.ravenna.ai/integrations/omnissa/agent-tools.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.