Overview of Key Definitions in Copilot

Last updated
Save as PDF

This article helps Gainsight admins and end users understand how Key Definitions enable Copilot to deliver accurate, context-aware responses using business logic and terminology.

Overview

Key Definitions help Gainsight Copilot interpret user questions using your organization’s business context. They ensure Copilot provides consistent, accurate, and relevant responses based on data-driven logic or defined business terms. Admins and end users can use Key Definitions to customize Copilot’s behavior according to their business requirements.

Prerequisites

Ensure Copilot is enabled for your tenant.
Only users with admin access can create, edit, delete, approve, or reject Key Definitions.
End users must have access to Copilot to view or suggest Key Definitions.

Benefits of Key Definitions

Improve Copilot accuracy and context understanding.
Standardize how data and business terms are interpreted.
Reduce inconsistencies in responses across teams.
Allow faster setup using reusable logic templates.

What are Key Definitions?

Key Definitions are standardized business data or instructions that help Copilot deliver accurate and context-aware responses.

Note: Key Definitions play a critical role in ensuring Copilot delivers consistent and relevant answers based on your organization’s data language and logic.

Types of Key Definitions

Type	Purpose
Data	Used to define logic or rules based on your company’s structured data. It helps Copilot identify what data to reference and how to process it, enabling accurate responses to your questions. You provide an instruction that describes the logic, and Copilot automatically generates the underlying configuration. You can review the generated setup, make adjustments if needed, and then save the definition once it is accurate.
Instruction	Used to define the meaning of a specific business term or phrase. It helps Copilot understand how your company uses that term in context, so it can respond accurately to questions that include it. You only need to enter a name and a short description to explain what the term means

Type

Purpose

Data

Used to define logic or rules based on your company’s structured data. It helps Copilot identify what data to reference and how to process it, enabling accurate responses to your questions.

You provide an instruction that describes the logic, and Copilot automatically generates the underlying configuration. You can review the generated setup, make adjustments if needed, and then save the definition once it is accurate.

Instruction

Used to define the meaning of a specific business term or phrase. It helps Copilot understand how your company uses that term in context, so it can respond accurately to questions that include it.

You only need to enter a name and a short description to explain what the term means

Note

Instruction-type Key Definitions do not always behave consistently. Write them clearly to ensure accurate results.
You cannot create a single Key Definition that covers multiple objects. A separate Key Definition must be created for each object.
You cannot create a Key Definition that uses an OR condition between fields.
Example: Company where ARR > 2M OR Status is Active.

Data Key Definition versus Instruction Key Definition

Understanding the difference between Data Key Definitions and Instruction Key Definitions ensures that Copilot interprets your organization’s language, logic, and data accurately.

Comparison Criteria	Data Key Definition	Instruction Key Definition
Purpose	Describes business terms based on structured data logic such as filters, thresholds, or report conditions.	Guides how Copilot interprets specific terms, fields, or behaviors during query analysis.
When to Use	Define criteria-based business segments, like ARR thresholds Map business-specific terms to data-level logic Enable Copilot to return data-driven responses	Specify which fields or objects Copilot should use such as ARR = ARR - Total Set default filters such as show only active companies Define organization-specific terminology Adjust how Copilot responds contextually to common questions
Example Business Use Case	Define High-value customers as companies with ARR > $2M	Use ARR - Total instead of the default ARR field in all ARR-related queries
Field Inputs	Name: High-Value Customers Logic: ARR > 2M in the Company table. Description: Identifies customers with ARR greater than $2M.	Name: ARR Custom Field Description: Use the ARR - Total field for ARR-related queries
How Copilot Uses It	When users ask, Show high-value customers, Copilot automatically applies this definition alongside the renewal condition to return accurate, context-aware results.	When users ask questions like Which customers have over $1M in ARR? or List accounts with high ARR, Copilot automatically understands that ARR refers to the ARR - Total field and applies that reference when generating responses.

Admin Capabilities

Admins can create, review, approve, and manage Key Definitions across the following supported objects:

Company
Call To Action
Task
Success Plans
Activity Timeline
User Objects

Create a New Key Definition

Key Definitions help Copilot interpret business terms and data logic in Gainsight. Admins can create Key Definitions to ensure Copilot returns accurate and consistent responses aligned with their organization’s terminology and data.

For more information on creating Key Definitions, refer to the Create a New Key Definition article.

choose the types of Key Definitions

Manage Key Definitions

The Manage Key Definitions section enables admins to manage existing Key Definitions and review end-user suggestions:

Key Definition: View, edit, or delete existing Key Definitions.
Suggestions: Review and approve or reject Key Definitions suggested by end-users in Copilot.

Configure Key Definition

Use the Key Definition tab to view, edit, or delete existing Key Definitions. To edit an existing Key Definition:

Navigate to the list of configured Key Definitions.

Manage Key Definitions, edit an existing Key Definition

To edit a Key Definition:
1. Click the Key Definition name from the list to open the edit screen.
2. Update the editable fields based on the Key Definition type:

Data: Name and Description, and Instruction
Instruction: Name and Description

Review the generated logic, output, and sources (for Data).
Click Save to apply the changes.

To delete a Key Definition:

Click the delete icon next to the Key Definition entry and confirm the deletion when prompted.

Click the delete icon next to the Key Definition entry and confirm the deletion when prompted

To change status of a Key Definition:

From the status label dropdown list next to the Key Definition,select Active or Inactive, and select the new status from the dropdown. The change is applied immediately.

From the status label dropdown list next to the Key Definition,select Active or Inactive, and select the new status from the dropdown

Note

Inactive Key Definitions are excluded from Copilot responses.
Copilot supports data-level or field-level permissions.
Key Definitions must be validated carefully before activation to avoid incorrect outputs.
Unsaved changes during Key Definition creation are lost if the process is exited prematurely.

Review Key Definitions Suggested by End-Users

Use the Suggestions tab to review and approve or reject Key Definitions suggested by end-users in Copilot.

To review end-user suggested Key Definitions:

Navigate to Copilot > Key Definitions > Suggestions. The list displays all Key Definitions submitted by end-users that are In Review.

Manage Key Definitions page showing user-suggested definitions with type, description, and date details

Select a Key Definition suggestion to review.
Review the fields based on the Key Definition type:

Data Key Definition: Name, Type, Description, and Instruction fields are required.
- End-users may or may not provide instructions when submitting a Key Definition suggestion.
- Admins can later add or update instructions based on the name and description.
- After updating the instructions, the admin clicks the Send Message icon to generate and review the logic.
Instruction Key Definition: Name, Type, and Description fields are required.
- (Optional) Modify the details to improve accuracy before approval.

Click Create Key Definition to approve and save the suggestion. The Key Definition is added to the Key Definition section and becomes available to all users. Once a Key Definition is approved or rejected, it is removed from the Suggestions list for admins.
Note: If a suggested Key Definition is not required or is redundant, reject the suggestion from the Suggestions section. Click the Reject Suggestion icon next to the suggestion in the list to reject it.

Manage Key Definitions page with an option to reject or approve a user-suggested key definition

End User Capabilities

End users can view existing Key Definitions and suggest new ones directly from Copilot.

View Key Definitions

To view Key Definitions:

Navigate to Copilot > Key Definitions.
Review the list of available Key Definitions configured for your organization.

review the list of available Key Definitions configured for your organization

Each Key Definition displays the following details:

Name
Description
Type (Data or Instructions)
Created Date
Status (Active or Inactive)

For Data type Key Definitions, additional details include:

Instruction
Copilot-generated logic
Expected Output
Source Tables (objects used)

Suggest a New Key Definition

To suggest a new Key Definition:

Navigate to Copilot > Key Definitions.
Click the Suggest Key Definition button.

Manage Key Definitions page in Copilot showing existing definitions list and the option to suggest a new one

Complete the required fields:

For Data: Name, Type (Data), Description, and Instructions (optional).
For Instruction: Name, Type (Instruction), and Description

Click Suggest Key Definition to submit your suggestion.

Note

The admin reviews and validates the Key Definition before adding it to the Key Definitions list.
You can check the status on the same screen. It appears as In Review, Accepted, or Rejected.

Use Out-of-the-Box Key Definitions for Quick Setup

Gainsight provides 13 out-of-the-box Key Definitions to help admins get started quickly. These preconfigured Key Definitions can be edited, deleted, or made inactive based on your use case. If any of the out-of-the-box Key Definitions do not meet your requirements, you can either deactivate or delete them.

Data Type Out-of-the-Box Key Definitions

Use these to define logic based on structured data for accurate Copilot responses.

Type	Name	Description	Instructions for Data Key Definitions
Data	Flagged/Starred CTAs	Interpret user terms 'flagged' or 'starred' CTAs as CTA.IsImportant = true.	CTAs where 'Is Important' = true.
Data	Backlog CTAs	CTAs which were due in last 15 days and status is 'Is closed' is NO	CTAs which were due in last 15 days and status is 'Is closed' is NO and 'is closed' is not null
Data	Overdue CTAs	CTAs where 'Is overdue' is true	CTAs where 'Is overdue' is true
Data	Risk CTAs (Open)	Open risk CTAs	CTA where Type IN ('Risk','Product Risk') AND 'Is closed' is NO
Data	Red Companies	Include companies with current score label as red	List active companies with current score.Label is `Red`
Data	Unassigned Companies (Active)	Shows a list of active customers with No csm assigned	list of active companies with No csm assigned
Data	No Recent Activity (30 Days)	Company where COUNT(Activity.ActivityID where ActivityDate >= TODAY-30) = 0	No direct way to solve this using company and timeline objects
Data	At-Risk Customers (via Risk CTAs)	Company where COUNT(CTA.ID where Type IN ('Risk','Product Risk') AND Status NOT IN ('Closed','Completed')) > 0	At risk customer type of KD utilization is not happening properly.
Data	At-Risk Renewals (Next 90 Days)	Company where Company.RenewalDate BETWEEN TODAY AND TODAY+90	changed this to renewals

Instruction Type Out-of-the-Box Key Definitions

Use these to help Copilot understand common business terms in your organization.

Type	Name	Description
Instruction	Default(Recent or upcoming) time range	Words like recent indicate a time filter of the last 30 days, while terms like upcoming or near future denote a time filter for the next 90 days.
Instruction	Active Companies Only (Default)	By default, restrict answers to companies where Company.Status = 'Active'. Exclude companies with a status of 'Churn' or 'Inactive', unless the user specifically requests these statuses.
Instruction	Default CTA Filters	By default, only show CTAs that are not linked to a Success Plan (i.e., the Success Plan field in the call_to_action object is NULL).
Instruction	Use Renewal Date Field for renewal use cases	Always use the Renewal Date field from the Company object when fetching companies that are renewing within a specific date range (e.g., days, months, quarters, years). Do not use alternative or derived fields such as Renewal Quarter, Days to Next Renewal, or any others.
	Flagged/Starred CTAs	Interpret user terms 'flagged' or 'starred' CTAs as CTA.IsImportant = true.

Limitations

You cannot create a single Key Definition that spans multiple objects.
End users cannot edit suggested Key Definitions after submission.
Queries with multiple conflicting logic instructions may not produce expected results.
Currently, only AND operations are supported between fields in KD and not OR.
For example: Company where COUNT(CTA.ID where Type IN ('Risk', 'Product Risk') AND Status NOT IN ('Closed', 'Completed')) > 0

Additional Resources

Copilot Best Practices and Known Limitations