Agent Toolkit

getUser

Tool name: getUser Description: Retrieves detailed information about a user by their userId, including email addresses, username, profile image, created/updated timestamps, and public metadata. Use this tool when you need comprehensive user information beyond just their ID. If the userId parameter is not provided, it will use the current authenticated user's ID. Example use case: When you need to display user profile information or check user attributes. . Arguments: - userId: (string): The userId of the User to retrieve.

getUserId

Tool name: getUserId Description: Get the userId of the current authenticated user if signed in, otherwise return null. Use this tool when you need to identify the current user but don't need their profile details. This tool takes no parameters and is the quickest way to check if a user is authenticated. Example use case: When you need to verify if a user is logged in before performing user-specific operations. . Arguments: Takes no arguments

updateUser

Tool name: updateUser Description: Updates an existing user's attributes in your Clerk instance. Use this tool when you need to modify core user information (NOT metadata). Important notes: 1. If the userId parameter is not provided, it will use the current authenticated user's ID 2. Only the provided fields will be updated, other fields remain unchanged 3. For updating metadata, use the specialized metadata update tools instead 4. Email and phone verification status cannot be changed with this tool Example use cases: 1. Updating a user's name, username, or other profile information 2. Enabling or disabling a user account 3. Setting a user's primary contact information . Arguments: - userId: (string): The userId of the User to update. - firstName: (string): New first name for the user - lastName: (string): New last name for the user - username: (string): New username for the user - profileImageUrl: (string): URL for the user profile image

getUserCount

Tool name: getUserCount Description: Retrieves the total count of users in your Clerk instance. Use this tool when you need to know the total number of users in the system. This tool takes no parameters and is an efficient way to get just the count without retrieving user details. . Arguments: Takes no arguments

getOrganization

Tool name: getOrganization Description: Retrieves a single organization by ID or slug. Use this tool when you need detailed information about a specific organization. You must provide either an organizationId OR a slug to identify the organization. Example use cases: 1. Displaying organization details on a profile page 2. Checking if an organization exists before performing operations on it 3. Retrieving organization metadata for application-specific functionality . Arguments: - organizationId: (string, optional): The ID of the organization to retrieve. Required if slug is not provided. - slug: (string, optional): The slug of the organization to retrieve. Required if organizationId is not provided. - includeMembersCount: (boolean, optional): Whether to include the members count for the organization.

createInvitation

Tool name: createInvitation Description: Creates a new invitation for a specified email address to join your application. Use this tool when you need to send invitation emails to new users. The invited email will receive an email with a sign-up link. You can customize the redirect URL and attach public metadata to the invitation. Example use cases: 1. Implementing a user invitation system for a private beta 2. Creating a closed registration system where only invited users can join 3. Pre-configuring user attributes via publicMetadata before they sign up . Arguments: - emailAddress: (string): Email address to send the invitation to. Required. - redirectUrl: (string, optional): URL to redirect users to after they accept the invitation. - publicMetadata: (Record<string,any>, optional): Public metadata for the invitation. - notify: (boolean, optional): Whether to send an email notification. Defaults to true. - ignoreExisting: (boolean, optional): Whether to ignore if an invitation already exists. Defaults to false.

revokeInvitation

Tool name: revokeInvitation Description: Revokes a pending invitation, preventing the recipient from using it to sign up. Use this tool when you need to cancel an invitation before it's accepted. This immediately invalidates the invitation link sent to the user. Once revoked, an invitation cannot be un-revoked; you would need to create a new invitation. Example use cases: 1. Canceling invitations sent by mistake 2. Revoking access when a prospective user should no longer be invited 3. Implementing invitation management controls for administrators . Arguments: - invitationId: (string): The ID of the invitation to revoke. Required.

createOrganization

Tool name: createOrganization Description: Creates a new organization in your Clerk instance. Use this tool when you need to programmatically create organizations. A name is required to create an organization. Other fields like slug, maxAllowedMemberships, and metadata are optional. Example use cases: 1. Creating organizations during user onboarding 2. Building a self-service organization creation flow 3. Migrating organizations from another system . Arguments: - name: (string): The name of the new organization. Required. - slug: (string, optional): A URL-friendly identifier for the organization. If not provided, created from the name. - createdBy: (string, optional): The user ID of the user creating the organization. Defaults to the current authenticated user. - maxAllowedMemberships: (number, optional): Maximum number of members allowed in the organization. - publicMetadata: (Record<string,any>, optional): Public metadata for the organization. - privateMetadata: (Record<string,any>, optional): Private metadata for the organization (backend-only).

deleteOrganization

Tool name: deleteOrganization Description: Permanently deletes an organization from your Clerk instance. Use this tool when you need to remove an organization completely. WARNING: This action is irreversible. All organization data, memberships, and invitations will be permanently deleted. Example use cases: 1. Implementing organization cleanup flows 2. Allowing users to delete their own organizations 3. Administrative operations to remove unwanted organizations . Arguments: - organizationId: (string): The ID of the organization to delete. Required.

updateOrganization

Tool name: updateOrganization Description: Updates an existing organization's attributes. Use this tool when you need to modify core organization information (NOT metadata). Only the fields you provide will be updated; others remain unchanged. For updating just metadata, consider using updateOrganizationMetadata instead. Example use cases: 1. Updating an organization's name or slug 2. Changing the maximum allowed memberships 3. Updating multiple organization attributes at once . Arguments: - organizationId: (string): The ID of the organization to update. Required. - name: (string, optional): New name for the organization. - slug: (string, optional): New slug for the organization. - maxAllowedMemberships: (number, optional): New maximum number of members allowed. - publicMetadata: (Record<string,any>, optional): New public metadata for the organization. - privateMetadata: (Record<string,any>, optional): New private metadata for the organization (backend-only).

updateUserPublicMetadata

Tool name: updateUserPublicMetadata Description: Updates the public metadata associated with a user by merging existing values with the provided parameters. Use this tool when you need to store or update user preferences, settings, or other non-sensitive information. Important characteristics: 1. A "deep" merge is performed - any nested JSON objects will be merged recursively. 2. You can remove metadata keys at any level by setting their value to null. 3. Public metadata is visible to the frontend and should NOT contain sensitive information. Example use case: Storing user preferences, feature flags, or application-specific data that persists across sessions. . Arguments: - userId: (string): The userId of the User to update. - metadata: (Record<string,any>): The public metadata to set or update. Use null values to remove specific keys.

updateUserUnsafeMetadata

Tool name: updateUserUnsafeMetadata Description: Updates the unsafe metadata associated with a user by merging existing values with the provided parameters. Use this tool when you need to store data that should be accessible both on the frontend and backend. Important characteristics: 1. A "deep" merge is performed - any nested JSON objects will be merged recursively. 2. You can remove metadata keys at any level by setting their value to null. 3. Unsafe metadata is accessible from both frontend and backend code. 4. Unlike public metadata, unsafe metadata is NOT included in JWT tokens. Example use case: Storing user data that should be modifiable from the frontend but not included in authentication tokens. . Arguments: - userId: (string): The userId of the User to update. - metadata: (Record<string,any>): The unsafe metadata to set or update. Use null values to remove specific keys.

updateOrganizationMetadata

Tool name: updateOrganizationMetadata Description: Updates the metadata associated with an organization by merging existing values with the provided parameters. Use this tool when you need to store or update organization-specific data without changing other attributes. Important characteristics: 1. A "deep" merge is performed - any nested JSON objects will be merged recursively 2. You can remove metadata keys at any level by setting their value to null 3. Public metadata is visible to the frontend 4. Private metadata is only accessible on the backend Example use cases: 1. Storing organization preferences or settings 2. Keeping track of organization-specific application state 3. Adding custom attributes to organizations . Arguments: - organizationId: (string): The ID of the organization to update. Required. - publicMetadata: (Record<string,any>, optional): The public metadata to set or update. Use null values to remove specific keys. - privateMetadata: (Record<string,any>, optional): The private metadata to set or update. Backend-only data. Use null values to remove specific keys.

createOrganizationInvitation

Tool name: createOrganizationInvitation Description: Creates an invitation to join an organization for a specified email address. Use this tool when you need to invite new members to an organization. The invited email will receive an email invitation to join the organization. You can specify the role the user will have upon accepting the invitation. Example use cases: 1. Building invite flows for organization member management 2. Implementing team expansion functionality 3. Creating administrative tools for organization growth . Arguments: - organizationId: (string): The ID of the organization to create an invitation for. Required. - emailAddress: (string): Email address to send the invitation to. Required. - role: (string): Role to assign to the user upon accepting the invitation. Required. - inviterUserId: (string, optional): User ID of the person sending the invitation. Defaults to the current authenticated user. - redirectUrl: (string, optional): URL to redirect users to after they accept the invitation. - publicMetadata: (Record<string,any>, optional): Public metadata for the invitation.

createOrganizationMembership

Tool name: createOrganizationMembership Description: Adds a user to an organization with a specified role. Use this tool when you need to programmatically add members to an organization. This creates an immediate membership without requiring an invitation process. The specified role determines what permissions the user will have in the organization. Example use cases: 1. Adding users to organizations during onboarding 2. Building administrative interfaces for member management 3. Migrating memberships from another system . Arguments: - organizationId: (string): The ID of the organization to add the member to. Required. - userId: (string): The ID of the user to add as a member. Required. - role: (string): The role to assign to the user in the organization. Required.

deleteOrganizationMembership

Tool name: deleteOrganizationMembership Description: Removes a user from an organization. Use this tool when you need to revoke a user's membership in an organization. This permanently breaks the membership relationship between the user and organization. The user will immediately lose access to organization resources. Example use cases: 1. Removing users who have left the organization 2. Building membership management interfaces with removal capability 3. Implementing self-service leave organization functionality . Arguments: - organizationId: (string): The ID of the organization to remove the member from. Required. - userId: (string): The ID of the user to remove from the organization. Required.

revokeOrganizationInvitation

Tool name: revokeOrganizationInvitation Description: Revokes a pending invitation to an organization. Use this tool when you need to cancel an invitation before it's accepted. This immediately invalidates the invitation, preventing the recipient from using it to join the organization. Example use cases: 1. Canceling invitations sent by mistake 2. Building invitation management interfaces with revocation capability 3. Implementing security measures to quickly revoke access . Arguments: - organizationId: (string): The ID of the organization containing the invitation. Required. - invitationId: (string): The ID of the invitation to revoke. Required. - requestingUserId: (string, optional): User ID of the person revoking the invitation. Defaults to the current authenticated user.

updateOrganizationMembership

Tool name: updateOrganizationMembership Description: Updates a user's role within an organization. Use this tool when you need to change a member's role or permissions. This updates an existing membership relationship between a user and an organization. The new role will replace the current role and change the user's permissions accordingly. Example use cases: 1. Promoting or demoting users within an organization 2. Building role management interfaces 3. Implementing admin-level controls for organization management . Arguments: - organizationId: (string): The ID of the organization containing the membership. Required. - userId: (string): The ID of the user whose membership is being updated. Required. - role: (string): The new role to assign to the user. Required.

updateOrganizationMembershipMetadata

Tool name: updateOrganizationMembershipMetadata Description: Updates the metadata associated with a user's membership in an organization. Use this tool when you need to store or update membership-specific data. Important characteristics: 1. A "deep" merge is performed - any nested JSON objects will be merged recursively 2. You can remove metadata keys at any level by setting their value to null 3. Public metadata is visible to the frontend 4. Private metadata is only accessible on the backend Example use cases: 1. Storing member-specific preferences or settings within an organization 2. Adding custom attributes to track member activity or status 3. Customizing a user's experience within a specific organization . Arguments: - organizationId: (string): The ID of the organization containing the membership. Required. - userId: (string): The ID of the user whose membership metadata is being updated. Required. - publicMetadata: (Record<string,any>, optional): The public metadata to set or update. Use null values to remove specific keys. - privateMetadata: (Record<string,any>, optional): The private metadata to set or update. Backend-only data. Use null values to remove specific keys.