Improve a Semantic Model
Let an agent add synonyms, example questions, instructions, descriptions, formats and calculations to a semantic domain through Semaphor MCP, with every change previewed and nothing typed by hand lost.
As an agent answers questions on a domain, it learns what the fields mean: that people say "revenue" for amount, that refunds are kept apart, which questions come up every week. It can write that back to the semantic model, so the next question, from any agent or any person, finds the right field. It uses the same two tools as every other change, semaphor_propose_change and semaphor_apply_change (see Making Changes).
What an agent can change
| Ask for | The agent proposes |
|---|---|
| "People call amount revenue and sales." | field.update with context.synonyms.add |
| "Say that amount is after discounts, before tax." | field.update with description |
| "Name it Order total." | field.update with label (the field's name never changes) |
| "Add 'What was revenue by region last quarter?' as an example question." | domain.update or dataset.update with context.examples.add |
| "Tell agents that amounts are in US dollars." | context.instructions on the domain, a dataset, a field or a metric |
| "Show amount as dollars." "A drop in returns is good." | field.update or metric.update with format or comparisonPolarity |
| "Hide the internal status column." | field.update with hidden: true |
| "Add a net revenue metric: revenue minus refunds." | calculation.add |
| "Net revenue should subtract discounts too." | field.update or metric.update with expression |
| "Group order dates by month." "Use the ship date as the default date." | field.update with granularity; dataset.update with primaryDateField |
| "Stop joining orders to the old customers table." | relationship.update with isActive: false |
How it goes
The agent reads what is there
It reads the dataset with semaphor_get_dataset_schema: each field's label, description, Context, format and the field that names a row.
It proposes, and you see one line per change
{
"domainId": "dom_abc",
"changes": [{
"op": "field.update",
"dataset": "orders",
"field": "amount",
"description": "Order total after discounts, before tax",
"context": { "synonyms": { "add": ["revenue", "sales"] } }
}]
}["Orders · Amount: description \"Order total\" → \"Order total after discounts, before tax\"; synonyms + revenue, sales (keeps 2)."]Each line says what changes, from what to what, and what stays. Nothing is saved yet.
You say yes, and it applies
A domain is shared by everyone in the project, so every semantic model change asks for a yes (confirm: needed). After you agree, the agent calls semaphor_apply_change with the proposalId. Open dashboards pick the change up within a minute.
Nothing you typed is lost
- Lists change one item at a time. Synonyms and example questions are added and removed by name. An agent can't send a whole new list, so names an author added by hand stay.
- A value changed since the preview stops the change. If someone edits a description, a label, instructions or a formula after the agent proposed changing it, apply saves nothing and says which values changed and what each is now. The agent reads the domain again and proposes from what is there.
- All or nothing. Up to 20 changes in one proposal are saved together, or none are.
- A name never changes. Cards refer to it. A rename is a label change.
Changes to the numbers
Most changes affect what agents read, not the numbers. A change to a definition (a formula, a default aggregate, a date grain, a primary date, a relationship turned off or rejoined) changes what cards show, so its line says what in the domain reads it, and the proposal is risk: medium:
["Orders · Revenue: formula \"SUM(amount)\" → \"SUM(amount) - SUM(refunds)\"; used by Average revenue, Revenue per customer; every card that uses it reads the new definition."]A formula that would turn a fact into a metric, or a metric into a fact, while other calculations on its dataset read it, is refused with their names: change those first.
Who can make these changes
Organization users with the Author role or higher, in the project's organization, logged in or with a token, the same rule as the domain page. End users never change a semantic model.
In your product's own assistant, the assistant proposes the changes and you save them: the Data model changes block lists each line, with Save change (or Save 2 changes, and so on) and Not now. If someone changed one of those values first, the block says which, and what it is now.
What stays on the domain page
Keys and unique keys, dataset sources and SQL, adding or removing datasets, unhiding a field, fact filters, date formats, composed dimensions and the formula of a metric across datasets. An agent that is asked for one of these says so and points you to the domain page.
What a Number Means
Compare a measure with an earlier period or a target, say which way is good, choose how the change shows, and run a table calculation such as a running total or a share of the total, through Semaphor MCP.
Live Changes in Embedded Dashboards
Let your own agent change the dashboard your user is looking at, unsaved, with Undo, using one token for the iframe and the MCP.