# Shared definitions for AI agents: one meaning per number, across every agent

> Why ChatGPT and Claude give different totals from the same sheet, and how a semantic layer of approved definitions and a glossary makes every agent use the same number.

Source: https://datatomcp.com/guides/shared-definitions-ai-agents · By Killian · Updated 2026-11-04

Ask ChatGPT and Claude for "revenue last quarter" from the same sheet and you can get two different numbers. Neither is lying: one summed every order, the other left out refunds, and a third agent might have counted only paid invoices. The fix is the one data teams have used for years, a **semantic layer**: write down once what each number means, and make every agent use that definition instead of inventing its own. This guide shows how to do it for spreadsheet data, without a data warehouse.

## Why agents disagree

An agent that gets a table and a question has to decide, every time:

- **Which column.** `amount`, `total`, `net_amount` or `amount_eur`?
- **Which rows.** All of them, or only `status = paid`? With or without refunds, test orders, internal accounts?
- **Which words.** Does "active customer" mean ordered in the last 30 days, or has an open subscription?

Each choice is reasonable, and each agent makes it again in every chat. Two agents, two choices, two numbers. A longer prompt helps one agent in one chat; it does nothing for the teammate who asks from Cursor tomorrow.

## What a definition is

A definition names a number and says exactly how it is computed:

| Name | Calculation | Filter |
|---|---|---|
| `paid_revenue` | sum of `amount` | `status` is `paid` |
| `active_customers` | count distinct of `customer_id` | `subscription_status` is `active` |
| `refunded_orders` | count of rows | `status` is `refunded` |

Add a description in your team's words ("Revenue from paid orders; refunds excluded"), and other names people use for it (aliases like `revenue` or `sales`), so an agent that asks for "revenue" lands on the same definition.

Words that aren't numbers go in a **glossary**: "active customer", "churned", "enterprise account". The glossary is text agents read before they answer.

## Set it up in datatomcp

<img src="/img/features/definitions.webp" width="1400" height="641" loading="lazy" alt="datatomcp Definitions page: a drafted total_amount waiting for approval, a suggestion agents keep asking for, the approved paid_revenue definition with who approved it and its aliases, and a glossary." />

1. **Add your data.** Connect a Google Sheet or upload a CSV or Excel file. datatomcp reads the columns and drafts a few definitions from them, like `total_amount = sum of amount`. Drafts are listed under **Drafted from your data** on the **Definitions** page.
2. **Approve or edit each draft.** Agents don't see a draft until someone approves it. Edit the calculation, add a filter, write the description and the aliases, then approve. Your name is saved with it.
3. **Add the definitions people ask for.** The **Agents keep asking for these** list shows calculations agents ran 3 or more times in 30 days without a saved definition, like "sum of units". One click saves it, so every agent uses the same one from then on.
4. **Fill the glossary.** Add the terms that mean something specific in your team.
5. **Connect your agents.** Add `https://app.datatomcp.com/mcp` to Claude, ChatGPT, Cursor or any MCP client, or call the [REST API](/docs/api).

## What changes for the agent

When an agent describes a dataset, it gets the approved definitions and the glossary along with the columns. When the user asks for revenue, the agent asks for the definition by name instead of rebuilding the sum:

```json
{
  "group_by": ["region"],
  "metrics": [{ "metric": "paid_revenue" }]
}
```

The database computes it with the saved column and filter, and the answer says which definition was used and who approved it:

```json
"meta": {
  "version": 14,
  "metrics": [{ "name": "paid_revenue", "fn": "sum", "column": "amount", "approved_by": "Ana" }]
}
```

When no definition fits, the server's instructions tell the agent to say so and explain how it computed the number, instead of passing its own calculation off as the team's. An unknown name gets the closest definitions back instead of a guess.

The same definition works from every client. Ask from Claude in the morning and from an n8n workflow at night: same name, same filter, same number, at the same data version.

## Check that it worked

- **Ask two agents the same question.** Both answers should name the same definition. The [audit page](/guides/audit-ai-agent-questions) shows whether repeated questions got the same answer.
- **Look at the map.** The workspace map draws which agents used which definitions, and calls that skipped a definition stand out.
- **Click through.** Every answer has a link to the rows behind it, so anyone can check a number without asking the agent again.

## FAQ

**Do I need a data warehouse or dbt?** No. Definitions sit on top of the sheets and files you already have. If you later move to a warehouse, the names and descriptions you wrote carry over as documentation.

**Can an agent change a definition?** No. Agents have read-only access. People with the editor role change definitions in the app or over the REST API (`PUT /datasets/{id}/metrics/{name}`).

**What if the sheet changes?** Definitions refer to columns. When a refresh renames or removes a column a definition uses, the definition is marked as broken ("Column amount no longer exists") for agents and on the Definitions page, until someone edits it.

**Can a definition be a ratio, like refund rate?** Not yet. A definition is one calculation (count, count distinct, sum, average, min or max) with filters. Save the two parts, like `refunded_orders` and `orders`, and the agent divides them.

**Is a definition the same as a saved query?** Close. A definition is one number with its filter. Agents combine definitions with their own grouping and filters ("paid revenue by region, this quarter"), so one definition answers many questions.

---

## About datatomcp

datatomcp is the AI-native data layer for teams without a data team. It makes a team's Google Sheets, CSV and Excel files AI-ready: one governed place every AI agent can ask, with exact answers computed by a database, shared definitions of what each number means, a full audit trail of agent questions, and charts. Agents connect over a remote MCP server (OAuth) or a REST API. Hosted in the EU. Facts, plans and limits: https://datatomcp.com/llms.txt. API reference: https://datatomcp.com/docs/api.