Getting Started

How to create a Tool?

Go to Admin console > Platform > Tools, here you will see a list of all available tools. You must have a Glean admin or app developer role to create tools.

On the top right, click on “New Tool”:

If you are creating a Gmail creation tool or jira creation tool, you can use one of the in-built templates, no coding required!

For other use cases, you can create a tool from scratch, with a little bit of coding!

Once you have selected an option, these are the steps to create a tool:

Step 1: Basic Info

Provide basic information for anyone to identify your tool.

• Display name - Name by which anyone can find your tool. This name will be shown to identify your tool in the tools directory.
• Display description - Description so anyone can know what your tool does.
• Unique identifier - Similar as Display name, but unique to your tool only. In case there are multiple tools with the same name, e.g. ticket creator, this identifier will be used to uniquely identify your tool.
• Tool type - Select the right tool type based on what your tool is meant to do, i.e. perform an action (Action type) or retrieve information (Retrieval type).

Tool types:

a) Action: Tools that will help users perform an action in an external app (e.g. creating a ticket, sending an email etc.)

Action tools are further divided into 2 categories:

• Execution
• Redirect

An action tool can directly perform the action on behalf of the user (Execution type) or simply redirect the user to the right URL where they can perform the action themselves (Redirect type)

For example, if a user asks Glean Chat: I need access to Salesforce, chat can use an action tool to automatically create an IT support ticket with the correct information filled, and just ask the user for confirmation in Glean Chat itself (Execution type) OR chat could also redirect the user to the right IT portal link with the request creation flow opened, and information pre-filled, and the user can confirm ticket creation on the portal itself (Redirect type).

b) Retrieval: Tools that are meant to retrieve information from an external application that may or may not be indexed with Glean (e.g. retrieving calendar events).

Step 2. Trigger Condition

When the user asks Glean Chat to do something, Glean Chat must figure out which tool to use to do what the user is asking. Glean Chat chooses the tool to use / trigger based on the information provided in the Trigger condition section.

For example, if the user messages Glean Chat:- I need access to Salesforce, Glean Chat needs to know which tool to use to perform this action. To find the right tool to use, Glean Chat will search through all the tools available and try to match this user query with the trigger conditions mentioned in all the tools.

In this case, the tool creator of the IT support Action tool, should have mentioned something like this in their trigger condition:

“Creates IT support tickets on JIRA. Use this action when the user wants to create a support ticket, needs access to something or wants help with any IT related issues. This could include: Access to slack, jira, gong, salesforce, sap successfactors, greyHR, keka, notion, coda, rippling, workday, loom, sharepoint. Issues with password, wifi, internet, permissions, laptop, monitor or any other IT related issue. Do not use this tool for general company related questions”

Apart from the main trigger condition text, tool creators can also provide some examples in the “Example queries” section, so that whenever a user mentions these queries/words in their chat message, the system knows that this particular tool should be used/triggered.

In the above example, the tool creator could have mentioned these example queries:

• I forgot my password for Notion
• Need to reset my password for gmail
• I need access to gong

This would ensure that whenever phrases like these are mentioned by the user in the chat, Glean Chat would know that this tool would be useful in resolving the user’s query. This list doesn’t have to include every possible user phrase, just a few common examples would be useful for Glean Chat to understand what type of tasks should this tool be used for.

Step 3: Functionality

Here you can define the specific configurations of the actions the tool is supposed to perform.

If you are using an in-built template of Gmail or JIRA creation, you will see a template that you can customize.

If you are creating a tool from scratch, you will see the option to upload an API spec.

Please refer to How do I configure the API Spec for a Tool? section for more information on this.

Step 4: Authentication

For tools with a server: Authentication describes how Glean should pass information required for a tools server to authenticate requests coming from Glean.

For JIRA Actions: Authenticate Actions in Jira

How do I test my Tool?

Once you have built a tool, you can test the tool using the link available at the bottom once you hit Save. Click on the link and try issuing queries that are expected to trigger the tool. If the tool does not trigger, consider tweaking the Trigger Condition section of the tool with clearer instructions.

How do I deploy my tool?

A Tool can be deployed either in Chat or in Ai Apps.

For Chat, tools can be deployed to all users (recommended only after thorough testing of the tool) or a subset of users for testing.

How do I configure the API Spec for a Tool?

(Note: This section is only relevant for tools that are built from scratch)

A .yaml or JSON file is required that describes the openAPI spec. The following are specifications on the openapi spec of the tool:

• Should contain a single endpoint defined in /paths (Example: /execute)
• Fields can be added either in requestBody.content or parameters. All fields in the requestBody.content and parameters should follow the following format:
  • Fields should not be nested (i.e., can only be of type string / number / integer / boolean , or an array of one of these types; or one of Glean’s built-in types)
  • To specify a fixed value use enum with a single value
  • All values which are not fixed can be guessed by the assistant
  • Fields can be marked required using regular openapi specifications

How do I build a server for my tool?

Refer to examples for a few example servers that Glean Assistant could interact with along with their respective API specs.