This summary is produced by the author, and not by AI.
In a Power BI semantic model you can set freeform text fields for each object (like tables, columns, and measures) to describe what they do, how to use them, or other information. These descriptions are a convenient and structured way to document each object for developers. They’re also helpful for users, since the descriptions (unlike DAX expressions) show when you hover on the object in Power BI Desktop:
The previous screenshot shows an example of how descriptions can be helpful for users, providing useful information and context about a measure.
Descriptions should provide information about the field, such as:
This is particularly valuable when the measure involves metrics that are contentious or ambiguous in the organization across teams, departments, and regions. Budgets, forecasts, and margins are common examples of this (from our consulting experience). It’s also helpful for master data, like dimensions such as customer, product, and vendor hierarchies.
Descriptions should not provide obvious or unrelated information:
In summary, descriptions should make any implicit or hidden information explicit that would be useful or actionable when using that field. It could thus be clarifying and informative, or it could specify an action that someone must take to use that field correctly or effectively.
In some cases, users might want to see the DAX expressions of a model that they are using to build reports, particularly with composite models. In this case, it might make sense to use descriptions to expose the expression. For instance, you can use a C# script in Tabular Editor or Python code in a Fabric notebook to sync these fields. Alternatively, this information can be obtained with the new INFO functions. However, the caveat is that adding (and maintaining) descriptions takes a lot of time. Before AI, it was very rare to see populated and helpful descriptions.
You can set descriptions one-by-one in the Properties pane, but a script is far quicker when you want to apply or sync them in bulk. For example, this Tabular Editor C# script stamps a description onto every measure that doesn’t already have one:
foreach (var m in Model.AllMeasures)
{
if (string.IsNullOrWhiteSpace(m.Description))
m.Description = "TODO: explain what this measure means and how to use it";
}
Nowadays, it’s quite common for people to use AI to generate descriptions for fields in their model. This is possible in a variety of ways, including Copilot, notebooks, C# scripts, and coding agents working with MCP servers or directly on TMDL files. However, the descriptions arising from AI might seem useful and better than nothing, but they can be problematic:
However, it’s undeniable that using AI can be helpful and convenient to populate descriptions. Thus, you can always use this approach but then review and update the descriptions to make sure that they are concise and useful. Never rely on any AI-generated outputs that haven’t been reviewed and approved by a human, first.
If you’ll use an AI or agent to query or modify your model, then AI-generated descriptions are especially useless. In these cases, the description is likely just adding extra words and tokens; the AI can already see the same information summarized in the description from other model metadata.
This is different if you are using completed Fabric Ontologies, or if you give an agent access to organizational context like other systems and documentation. In this case, the agent might give more useful suggestions for descriptions. However, you should always review these outputs before using them.
Descriptions are especially important for AI. Conversational BI tools like Copilot, data agents, and third-party agents (which we’ll lump into a single group called agents for simplicity) use descriptions when they query or manage the model via MCP servers or APIs. These descriptions become part of the context that the agent uses to “understand” the model and improve its outputs and actions, together with other information like field names and metadata. Bad or unclear descriptions can also lead to worse agent outputs.
Consequently, many people say that this is good; more people are more likely to write descriptions for their models, which can be used by both human users and agents. However, this is incorrect. Often, a description for an agent looks very different than a description for a user. Consider the following examples for descriptions of a measure, Standard Margin:
The following is an example of a description that’s intended for an agent:
“When a user asks for Margin, they are referring to the Standard Margin (this measure). You should use this field, and not the Gross Margin or Contribution Margin.”
The purpose of this description is to ensure that, i.e., Copilot takes this field if a user asks "What is the margin" or similar. It's an emphasis in addition to a synonym. But a human user or developer doesn't benefit from seeing this; they're just colloquially referring to it as "margin"; they can see from the measure name that it's "standard margin". If they see this, they assume this is a field for AI, so if there's relevant information for them, they might stop reading and not see it.
Now, contrast this with an example of a description that’s intended for a human user:
“Standard margin = revenue minus standard cost of goods sold, using the valuated production cost from the manufacturing plant (SAP: VBAP-WAVWR and not COPA).”
The purpose of this description is to help a human user understand how "Standard Margin" is calculated, because it's a contentious metric in the large organization and everyone's arguing about it all the damn time. The description makes it unambiguous and even refers to the SAP source data fields. This information isn't relevant for Copilot to generate DAX queries; maybe it even confuses it. It might be useful for Copilot to answer the question "how is standard margin calculated", though.
When you need to provide explicit information to AI and agents, consider using other properties and mediums:
Perhaps in the future, the Fabric ontology could be another alternative. However, it is currently too early to say. Generally, you should only use descriptions when you would provide the same information to both users and agents. However, if you are writing good descriptions, this won’t typically happen.
Descriptions are freeform text fields useful for developer documentation and instructions for both human users and AI agents. Good descriptions can help people and AI use your model. A good description should make any implicit, non-obvious information about that field explicit, and doesn’t just summarize obvious information already in the name or table and display folder. And since the same description rarely serves a human and an agent equally well, be deliberate about who you’re writing each one for.
Take your semantic models further with Tabular Editor.
Give Tabular Editor a spin