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:
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. Just make sure you always read the things AI generates before you toss them into production or put them in front of users.
Now, with regards to agentic development, 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. Here you should instead rely on skills, documentation, and other forms of AI context, which we’ll cover in later articles in a coming series and training about agentic development.
To give a concrete example, consider a model that has a measure Sales & Shipped to report revenue. The measure could contain a specific calculation and the model metadata could make it clear that it phases revenue by shipment date instead of billing date. However, nothing in the model metadata says why that is the case. Talking to a business user in the sales community would reveal that the reason is because many stores bill at the end of the month, meaning that a disproportionately high volume of revenue ends up in the last few workdays. This isn’t representative of real intra-month performance, so the business recognizes revenue by shipment date, instead. Once the month is closed by finance, all past months are recognized by the proper billing date. Therefore, if a month is in progress, a query should use Sales & Shipped, but if the month is in the past and closed, then it should use Gross Sales.
A description on one or both of these measures could clarify this in brief, both for users and agents. The clarification would produce query results that better reflect the business process and user expectations. Importantly, though, this is an example of implicit information made explicit in context.
You can get better results with AI-generated descriptions if you integrate the agent with Fabric IQ or organizational context, such as other systems and documentation.
Descriptions are especially important for AI. Conversational BI tools like Copilot or data agents use descriptions for queries, and coding agents use them to manage or change the model via other tools. 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, as we mentioned, above.
However, even if agents could write good descriptions with complete context, there’s a more nuanced issue, here. Specifically, a description that’s good for an agent looks very different than a description for a user or developer. 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, which aren’t exposed to users and are specifically designed for use by technical processes, pipelines, or AI:
You can also use the Fabric ontology to store information about data fields and their relationships, as well as other semantic information. At present, the ontology has limited support for freeform context, but this might be a welcome addition in the future to store data and process context with separate concerns from actual data and reporting artifacts…
A recent article from Anthropic emphasized the importance of prioritizing your metadata and context. In semantic models, this includes naming conventions, descriptions, AI instructions, and so on. In the past, we used to neglect these elements as optional hygienic documentation. Now, it’s something that helps us scale to get better results from AI both with analytics and agentic development.
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.
Use Tabular Editor 3 and the CLI to write descriptions for your semantic models.
Give Tabular Editor a spin