Business users ask questions using the language of work, pay, benefits, and performance. An AI Agent needs enough business context to connect those questions to the intended data and to interpret that data correctly. AI Descriptions provide that context as semantic metadata for the dataset and its fields.
This post uses a sample Workforce Details dataset for HR analytics. It includes employee and job information, employment arrangements, compensation, locations, leave balances, benefits, stock options, and performance data. The examples below narrow that broad dataset to four common workforce questions.
For the basic setup and reusable description templates, see the companion post AI Description Templates for OAC AI Agents. This post focuses on the practical result: the difference a well-written description makes to an AI Agent response.
The following examples show how AI Descriptions help an AI Agent understand business questions and use the intended data.
How the examples were tested
- Ask a natural business question against the indexed dataset.
- Review the initial response and identify the missing business context.
- Add the required AI Description or model a calculated field when the business metric does not exist.
- Save the AI Description, and test the same question in the AI Agent.
Examples
In the first two examples, the required fields already exist. AI Descriptions help the agent connect the business question to the right field and aggregation.
Example 1: Variable pay opportunity
Business question
Which employment contract types have the highest average variable-pay opportunity?
Why the field needs context
The dataset contains Bonus Pct, but that name alone does not establish that it represents variable-pay opportunity or that it should be averaged for this question.
AI Description added
Employee annual bonus opportunity, expressed as percentage points of base salary. Use average Bonus Pct for questions about variable pay or bonus opportunity. It is not a bonus amount in USD.
Result
The agent can connect variable-pay opportunity to Bonus Pct and compare the average by Employment Contract.
Example 2: Benefits Participation
Business question
Which employee types have the lowest employee benefits participation rate?
Why the field needs context
Benefits Enrollment is a binary indicator. A participation rate is the average of that indicator within each employee type, not the sum of enrolled employees.
AI Description added
Binary employee benefits-enrollment indicator. A value of 1 means enrolled and 0 means not enrolled. For benefits participation rate, calculate the average of Benefits Enrollment within each requested employee group and show it as a percentage. Do not use the sum as a participation rate.
Result
The agent can now calculate and compare benefits participation rates by Employment Type.
For a new calculated field, select the column in the indexing list and run the index. Then add its AI Description, save it, and use it with the AI Agent.
The next two examples use a calculated field because the required business metric or grouping is not stored directly. Create the field first, then add an AI Description that explains what it represents and when the agent should use it.
When a calculated field is needed
Example 3: Stock option participation
Business question
Which employee types have the lowest share of employees with stock options?
What is missing
Stock Options stores the number of options granted to an employee. It does not directly represent the share of employees who receive any stock options.
Calculated Field
Stock Option Participation = CASE WHEN Stock Options > 0 THEN 1 ELSE 0 END
AI Description Added
Binary participation indicator derived from Stock Options. A value of 1 means the employee has one or more stock options; 0 means none. For the share, rate, or percentage of employees with stock options, average Stock Option Participation within the requested group. Do not use Stock Options.
Result
The agent can use the calculated indicator to return a valid stock-option participation rate by Employment Type.
Example 4: High Performing Employees
Business question
Which departments have the highest share of high-performing employees?
What is missing
High performing is a business definition, not a stored field. For this example, the approved definition is a Performance Rating of 4 or 5.
Calculated Field
High Performer Indicator = CASE WHEN Performance Rating >= 4 THEN 1 ELSE 0 END
AI Description Added
Binary indicator based on Performance Rating. A value of 1 means rating 4 or 5; 0 means below 4. For high-performer rate, average High Performer Indicator within the requested group and show a percentage.
Result
The agent can apply the approved definition consistently and compare high-performer rates by Department.
The Value of AI Descriptions
These examples show the same principle at two levels. When a suitable field already exists, an AI Description gives the agent the business meaning needed to select and interpret it correctly. When the required metric or grouping does not exist, a calculated field creates the approved business definition and the AI Description explains when to use it.
Start with the questions business users actually ask. Add only the metadata and modeling needed to answer those questions reliably. That keeps the agent grounded in the data while allowing users to work in familiar business language.
Call to Action
- AI Descriptions for datasets
- AI Descriptions for subject areas
- AI Descriptions Templates for AI Agents
- OAC AI Agents Best Practices
