How to Resolve Conflicting KPI Names Before an AI Agent Answers

Resolve conflicting KPI names by mapping each business term to an approved metric or dimension, documenting the scope where that mapping applies, and asking for clarification when more than one meaning remains valid. Keep calculations in their governed source, including dbt where it owns the metric. A glossary should help an agent choose the right definition before it queries data.

The useful test is whether the agent can distinguish a synonym from a different business concept. Two teams can use different names for the same measure. They can also use the same name for different measures. Those situations need different repairs.

Documentation reviewed October 10, 2026. The worksheets, example, and decision policy below are recommended operating practices. They are hypothetical and are not Orion configuration formats or claims about a customer deployment.

Why do conflicting KPI names produce wrong answers?

An agent can run valid SQL and still choose the wrong measure. A request for “sales” might refer to signed contract value, recognized revenue, or the number of completed orders. Calling all three synonyms hides a business distinction that the query engine cannot resolve for you.

The ambiguity can also concern a dimension rather than a KPI. “Program,” “product line,” and “business unit” might describe the same grouping in one department and different hierarchies in another. Choosing the correct revenue measure will not fix an incorrect grouping.

Google's Looker Conversational Analytics guidance, updated October 9, 2026, identifies unclear definitions and naming conflicts as causes of incorrect field selection. It recommends clear labels, descriptions, and synonyms. This is a documented problem in an established semantic-model workflow, not evidence that every organization needs another context platform.

A business glossary is a maintained mapping between the words people use and the approved concepts those words refer to. For AI analytics, that mapping needs enough scope and examples to guide selection. A list of definitions without instructions for ambiguous requests leaves the hardest decision to the agent.

How do you tell a synonym from a conflicting definition?

Compare the concept behind each term before merging names. Check the counted entity, calculation, population, time basis, units, and grouping. Similar names or matching results in one reporting period do not establish equivalence.

Use the following classification with the owners of the affected reports. It is an editorial decision aid, not a software feature.

An alias is an alternative name for the same concept within a stated scope. A metric variant is a different approved measure. A historical definition is a meaning that applied during a particular period. Keeping these categories separate prevents a vocabulary cleanup from silently changing reporting logic.

What should a term-resolution worksheet contain?

Start with one recurring question that causes confusion. Record the exact words users type, then connect those words to existing governed references. The worksheet should help a reviewer decide what the agent must select, clarify, or leave unresolved.

The example below describes a fictional service business. The identifiers are illustrative, not supplied dbt models or an Orion import format. “Sales” has two legitimate meanings, so the worksheet preserves both.

Keep the metric formula in its authoritative system. The worksheet points to it and describes usage. If the candidate concepts have no approved definitions, the next step is metric definition work with their owners, not adding more aliases.

An unresolved row is useful evidence. It shows where a human decision is needed. Do not fill it with an agent's best guess to make the inventory look complete.

Which vocabulary belongs in dbt or LookML, and which belongs in context?

Put durable metadata beside the field or metric it describes when that system supports it. Keep the calculation, grain, filters, and valid relationships under the existing data team's governance. Add task-specific interpretation where it can be maintained without duplicating those definitions.

The dbt Semantic Layer, updated September 29, 2026, centralizes metrics on existing models and uses MetricFlow for their execution. dbt's metric specification, updated July 20, 2026, distinguishes the unique reference name from the display label and description. Preserve those references when writing a glossary instead of creating another implementation of the formula.

For Looker, Google's guidance prioritizes field-specific descriptions and synonyms in LookML and advises against duplicating them in agent instructions. User goals and qualitative decision context can sit around the model. Apply the same ownership principle to your stack, while checking the metadata fields and consumer behavior it actually supports.

A company-wide alias that is always valid differs from a mapping that applies only to one review. Avoid loading a finance-specific interpretation as a global rule. Access permissions are a separate concern: a term mapping explains meaning and does not authorize access to the underlying data.

For the broader boundary, see Semantic Layer vs. Business Context. This workflow focuses on resolving the words in a request before choosing its metric and grouping.

When should the agent ask a clarifying question?

Ask when the available, authorized context leaves multiple valid interpretations that would change the answer. The purpose is to resolve the analytical choice with the smallest useful question.

For “September sales by program,” a useful clarification is: “Do you mean recognized revenue for the finance review or signed contract value for the sales review? Which program grouping should I use?” Use only choices the requester is allowed to know about. If the measure is clear but the grouping is ambiguous, ask only about the grouping.

Use this recommended decision policy:

1. Read the stated task and requested concept. Do not infer a reporting purpose solely from someone's department or chat channel.
2. Retrieve the approved mapping and candidate metric or dimension references within the authorized scope.
3. If one applicable mapping remains, use it and name the selected concept in the answer. Make any approved default visible.
4. If more than one meaning remains, ask a targeted clarification. Do not choose the most common label or average the candidates.
5. If sources conflict or none is approved, describe the missing decision and route it to the responsible owner. Exploration can be labeled as provisional when the team's policy permits it.

This policy is a behavior to implement and verify in the intended agent. A written instruction alone does not prove that every client retrieves the right mapping or follows it.

How do you prove the mapping works before using it widely?

Review selection separately from numerical correctness. An agent can accidentally return the same number using the wrong concept. First inspect the selected metric and dimension, then reconcile the result under the same period, filters, identity, and data cutoff.

Use these six checks for the hypothetical worksheet:

1. Ask “September recognized revenue by product family.” Expect the explicit measure and grouping, with no unnecessary clarification.
2. Ask “September sales by program for the named finance review.” Expect the scoped alias to resolve to the same approved references.
3. Ask “September sales by program” without the review scope. Expect clarification wherever multiple approved meanings remain.
4. Ask the equivalent question for the sales review. Expect its approved contract-value measure, preserving the distinction from finance.
5. Ask a question spanning a definition change. Expect the system to identify the relevant effective boundary or explain that historical mapping is unavailable.
6. Repeat as a user with restricted access. Expect only authorized choices and results; a glossary must not reveal hidden measures or bypass permissions.

Record the request, supplied context, mapping source and revision where observable, chosen references, clarification, query or tool call, result, and reviewer disposition. Where the product does not expose a revision or historical input, record the limitation instead of assuming reconstruction is possible.

For broader release checks, use How to Test an AI Context Layer. For adoption across consumers, use Keeping Claude, Slack, and BI Definitions Consistent. Correct term selection is one input to those workflows.

How can Orion by Gravity support this work?

Orion by Gravity offers documented places to maintain and inspect business context. Its Knowledge Base pages support Markdown editing, revision history, project selection, and optional broader defaults. Locked pages support change requests, while creators and admins have documented direct-edit exceptions. These provide a place for a reviewed term worksheet; they do not establish an automatic alias resolver or mandatory independent approval.

Orion's dbt connection guidance describes enrichment with model descriptions and lineage. That is useful source context, but it is not proof that a selected term invokes a governed MetricFlow metric. Demonstrate the actual calculation route in the intended deployment.

The analysis documentation describes notebooks containing instructions, logic, and code. Use the available record to inspect the selected concept and computation. The MCP tools reference documents knowledge search and page retrieval for compatible integrations. Verify what each client receives and uses; this does not imply control over every third-party agent.

The classification, resolution policy, and six checks in this guide are proposed operating practices. Validate them with a real mapping and ambiguous request before widening a pilot. If existing semantic-model metadata and its agent already handle the problem, improve that system first. A separate context workflow is useful when maintained task-specific meaning and review address a demonstrated gap.

Frequently asked questions

Should every team use the same KPI name?

Give the same concept a stable reference and preserve useful local aliases. Give different concepts distinct approved names. Forcing bookings and recognized revenue under one “sales” label hides a difference rather than resolving it.

Can we treat matching numbers as proof that two terms are synonyms?

No. Different populations or calculations can coincide for one period. Compare the entity, logic, grain, filters, units, and time basis with the metric owners before approving an alias.

Can a business expert fix vocabulary without changing dbt code?

A business expert can propose a usage mapping or correct an operating note in an editable context system. If the error is in governed field metadata or the calculation, send the change through that source's ownership process. The location of the error determines the repair.

Does the requester's department determine the right metric?

A department can supply context, but it does not establish the task. A finance employee may ask about bookings. Prefer the explicit question and approved review scope, and clarify when the remaining interpretations differ.

What should happen to retired KPI names?

Record the replacement and effective date, along with the former meaning when historical reporting needs it. A renamed concept can have an alias; a changed calculation requires a version boundary. Confirm whether the system can retrieve historical definitions before relying on them.

What is the best first pilot?

Choose a recurring request with two known interpretations and available owners. Fill in the worksheet, agree on the clarification, and run the six checks. Approve wider use only after reviewers can see that explicit names, scoped aliases, and ambiguous requests produce the intended selections.

See Orion by Gravity for the product and AI business intelligence tools for broader options. Bring a real disputed term and its approved references to a pilot so the discussion starts with an observable decision.