Writing good descriptions for semantic model columns and measures

Key takeaways

• Descriptions document your fields: They provide useful information about fields and how to use them for developers, users, and AI/agents, helping people understand your model and better use it to analyze data.
• Make hidden information explicit: Good descriptions provide information not already obvious from the object name or its table and display folder; be concise and structured, give information that's informative or actionable, and review any AI-generated descriptions.
• AI and human descriptions differ: AI needs different information than users, because they aren't doing the same thing, so a description written for an agent often looks very different from one written for a person.

This summary is produced by the author, and not by AI.

What are descriptions and why are they important

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.

What goes in a description?

Descriptions should provide information about the field, such as:

• How it is calculated.
• Where the field comes from (i.e. source system data mappings) if users know this.
• Implicit information pertaining to how the field should be used in reports and queries.
• Instructions about how to use the field in the model, particularly when there are conditions, exceptions, or unexpected filters and interactions in the calculation.
• Where to find other relevant calculations, or clarifications about nomenclature.
• Recommendations for fields (to aggregate, or alternative measures), filters, chart types, and analyses.

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.

What doesn’t go in a description

Descriptions should not provide obvious or unrelated information:

• Meaningless information, like describing the Sales measure as the “Total sum of sales”, or describing Sales YTD as “The sales aggregated year-to-date”. It might be more interesting to know whether there are certain fields, dynamic currency conversion, or a specific aggregation logic applied.
• Verbose descriptions of fields, technical functions, or model structures that users don’t know or understand. Examples might be calling Orders as “The sum of net order quantity multiplied by net order price with USERELATIONSHIP to fields from the Date table.” This is much less helpful than saying “Order intake phased by the Sales Order Line Creation Date rather than the document header date. Uses the price at order creation.”
• DAX expressions, which are too complex, redundant, and not formatted properly in a description.

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.

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";
}

Don’t rely on AI to generate descriptions

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:

• If they only use the model as context, then they miss important and relevant information that should go in that description.
• AI is often verbose, producing text that gives a high cognitive load to read and understand.
• Descriptions are often unhelpful or sometimes even incorrect.

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.

A good description for AI is different than one for users

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:

Descriptions for AI and agents

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.

Descriptions for humans

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.

Alternatives to descriptions for AI and agents

When you need to provide explicit information to AI and agents, consider using other properties and mediums:

• AI instructions, which are model-scoped, but let you provide freeform context like a markdown or text document. You could refer to specific fields in bullet points.
• Code comments, which can also be specific to certain parts of the expression. This only works with certain configurations and experiences, though. Comments aren’t exposed to users.
• Annotations, which you can set in Tabular Editor, or in TMDL metadata (i.e. with an agent). Annotations are a bit more complex, though, and are only guaranteed to work with third-party agents (it’s unclear if they work with Copilot and Fabric data agents).

For further reading

• Use Copilot to create measure descriptions (Microsoft Learn). The official how-to for generating descriptions with Copilot, useful to know exactly what the AI starts from (your DAX) and therefore what it can’t know without your help.
• Extract measures and metadata from Power BI semantic models using DAX (Max Wikström). A practical look at the INFO functions for pulling descriptions and other metadata out of a model, handy for auditing which objects still need one.
• Naming conventions for Power BI semantic models (Tabular Editor). Naming and descriptions are the two halves of documenting a model; clear names mean you need fewer descriptions in the first place.
• How to write good AI instructions for a semantic model (Tabular Editor). The model-scoped counterpart to field-scoped descriptions, for when the context you want to give an agent isn’t about one specific field.

In conclusion

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.