Skip to main content
Gainsight Inc.

Key Definitions in Copilot

  1. Last updated
  2. 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.

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

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

To create a Key Definition:

  1. Navigate to Copilot > Key Definitions.

Create a New Key Definition

  1. Click Create Key Definition. The Create Key Definition dialog box appears.

choose the types of Key Definitions

IMPORTANT

  • When creating a Key Definition, be specific and clear with both the name and description. Copilot uses these fields to determine which Key Definition to apply when responding to queries. Avoid using internal-only language, abbreviations, or overly generic terms.
  • There is no limit to the number of Key Definitions you can create in Copilot.

Note

  • You cannot add Key Definitions in bulk.
  • Use Instruction type for simple, descriptive terms that do not rely on data logic.
  • Use Data type for complex Key Definitions that reference structured data, objects, or filters. This type behaves like a report and allows admins to view and validate referenced data for accuracy.

  1. Select the type of Key Definition you want to create:

  1. Click Create Key Definition. The newly created Key Definition is saved.

Recommendation: When you create a new Key Definition, Copilot automatically references existing definitions for the same object or context. For example, a new CTA definition also includes logic or instructions from previously defined CTA-related definitions. To avoid duplication or logic overlap, review existing definitions before creating a new one.

For detailed guidance and examples, refer to the Copilot Best Practices and Known Limitations article.

Create a Data Type Key Definition

If you have selected DATA, complete the required fields:

Field Field Explanation
Name Enter a meaningful, descriptive name.
Type Auto-selected based on context.
Description Provide a brief explanation of the key definition’s purpose.
Instructions Add a prompt-style instruction for Copilot to generate logic and output.

Tip: Be specific and avoid using internal-only terminology or abbreviations.

Example

Instructions added:

  • Include CTAs due in the last 15 days.
  • Also include CTAs due in the last 30 days.

Copilot merges both instructions and displays only the final logic:

Includes CTAs with a Due Date in the last 30 days.

Condition: Due Date is on or after 30 days ago

Note: Copilot displays only the resulting logic, not the full list of instructions.

Copilot displays only the resulting logic, not the full list of instructions.

Review the Output Preview

After adding an instruction to a Key Definition, Copilot displays a detailed preview to help you validate and refine the logic before saving. The following table explains each component of the preview interface.

Section Description
Displays the filters and rules Copilot applied based on your instruction. Logic: Displays the filters and rules Copilot applied based on your instruction. For example: There are 181 companies with an ARR greater than 1,000, listed below within the next 90 days.
Summary Explains what is included in the result

Summary: Explains what is included in the result. For example: 

Company_Arr > 1000 (Identify companies with Annual Recurring Revenue greater than 1000)
Key Definitions Considered- Lists any existing Key Definitions that Copilot used to build the current logic Key Definitions Considered: Lists any existing Key Definitions (by name and description) that Copilot used to build the current logic.
Tip- When asking a question about a specific entity follow the best practices

Tip: When asking a question about a specific entity such as a Company, Relationship, Success Plan, CTA, or Task follow these best practices for accurate results: 

  • Use single quotes around the entity’s exact name.
  • Clearly mention the entity type.

Example: Summarize 'New CS Project - Assign Sheet' CTA. Don’t miss out on any information.
Copy Icon and Feedback Icons

Copy Icon: Allows users to copy the entire Copilot response for use.

Feedback Icons: Icons that let users rate Copilot’s response accuracy or relevance (thumbs up/down).
Note: If you select thumbs down, you can provide additional comments like Not Accurate, Incomplete Info.
Displays a sample of the actual data Copilot will reference when responding to queries. Output tab: Displays a sample of the actual data Copilot will reference when responding to queries. Use this to confirm accuracy before saving the Key Definition.
Lists data tables or objects Copilot references. Useful to ensure relevant data is being pulled Sources tab: Lists data tables or objects Copilot references. Useful to ensure relevant data is being pulled.
Info Tooltip, Visualization Selector, Expand icon.

Info Tooltip: Accessible through the info icon or “Find out how” link. Opens the explanation panel to display backend logic, filters, tables used, and clarification questions.

Visualization Selector: Opens a panel with multiple visualization options like table, bar chart, pie chart, line chart, and more. Users can switch how the Copilot response is displayed based on their analysis needs.

Expand icon: Opens the table in a full-screen or detailed view.
tabs appear when you click the Info icon or Find out how

The following tabs appear when you click the Info icon or “Find out how,” offering a detailed view of how Copilot processes your query.

  • Details: Explains how Copilot generates the response, including the filters, tables, and logic it uses.
  • Code: Displays backend logic or pseudo-code behind the response, if available.
  • Sources: Lists the data sources or objects used in generating the response.
  • Clarification Questions: Shows assumptions or follow-up questions Copilot considered.
  • Definitions: Displays Key Definitions applied during the query for standardized interpretation.

 Note

  • Copilot uses standard field mappings by default, which may not align with custom configurations. Review all logic carefully.
  • Admins can add additional instructions to refine behavior but cannot directly edit the original instruction text. This can lead to confusion in understanding the complete logic if multiple instructions accumulate over time.
  • The Output preview does not show all added instructions. Use the Logic and Summary sections to infer the final behavior.

Create an Instruction Type Key Definition

If you have selected INSTRUCTION, complete the required fields:

Field Field Explanation
Type Auto-selected based on context.
Name Enter a meaningful, descriptive name.
Description Provide a brief explanation of the key definition’s purpose.

Tip: Keep names and descriptions simple and intuitive. Use consistent terminology aligned with your business language.

Keep names and descriptions simple and intuitive. Use consistent terminology aligned with your business language

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:

  1. Navigate to the list of configured Key Definitions.

Manage Key Definitions, edit an existing Key Definition

  1. 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 
  1. Review the generated logic, output, and sources (for Data).
  2. 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:

  1. 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

  1. Select a Key Definition suggestion to review.
  2. 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.
  1. 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: 

  1. Navigate to Copilot > Key Definitions.
  2. 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:

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

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

  1. Complete the required fields:

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

  1. 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
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
    Custom Filter
    Guides
    Draft Workflow
    Ready to Publish
  2. Tags
    1. Copilot
    2. Key Definitions
    3. Key Definitions in Copilot