29 Jul 2026 Power BI Metadata Enrichment Skill using Agentic AI

The introduction of Power BI Desktop projects (PBIP), in preview at the time of writing, has transformed how semantic models are managed, particularly through the use of Tabular Model Definition Language (TMDL). By exposing report and semantic-model definitions as readable plain-text files rather than packaging them within a traditional PBIX file, PBIP makes the model less of a “black box”. This shift has created an opportunity to automate the laborious manual documentation process and, simultaneously, to solve a new challenge: preparing semantic models for AI-assisted experiences.

Modern businesses are increasingly using Copilot in Power BI to query data through natural language. As a result, semantic-model metadata quality is no longer merely a documentation concern, but key to helping AI systems to interpret business questions with greater accuracy, context, and consistency.

To address this need, we developed the Power BI Metadata Enrichment Skill, an agentic solution that automates the optimisation and linguistic enrichment of semantic models by generating object descriptions and synonyms. By improving both technical documentation and linguistic metadata, this Skill helps to prepare semantic models for more reliable AI-driven natural-language interaction.

What is the Power BI Metadata Enrichment Skill and How Does it Work?

The Power BI Metadata Enrichment Skill is a workflow designed to enrich Power BI semantic models. It generates technical and business descriptions for tables, columns, measures, and any DAX user-defined functions present in the model.

The Skill was developed through an iterative agentic AI workflow, in which an AI coding agent was used to analyse the PBIP structure, interpret the TMDL files, generate the initial automation logic, and progressively refine the workflow through prompts, validation, and successive adjustments. Codex was the AI coding agent used in this implementation, although comparable workflows could be developed with tools such as the GitHub Copilot coding agent, Claude Code, or Gemini CLI.

The Skill operates in two sequential phases:

Phase 1: Descriptions (Description-First)

The Skill performs a comprehensive analysis of the semantic model to generate or improve concise descriptions. For the Skill to generate accurate documentation, it must understand the model as a whole, including its tables, measures, relationships, and dependencies.

Before making any edits, the Skill carries out a discovery phase to inspect the model’s technical structure. It analyses the relationships file (relationships.tmdl) to identify relationship keys, as well as helping to infer the intended grain of the data and to understand filter propagation paths. The Skill also examines the expressions file (expressions.tmdl) to map parameters, data source references, and shared expressions. It reviews report definition files (*.Report/definition) when business meaning is ambiguous. This initial structural understanding ensures that each generated description provides valuable context for both human developers and AI tools, rather than simply restating object names or producing generic documentation.

Once this discovery step is complete, the Skill runs the documentation phase across all table definition files and the functions.tmdl file, following a set of requirements and validation checks:

• Native syntax: The Skill writes descriptions using TMDL’s native triple-slash (///) syntax immediately above each object declaration, rather than attempting to introduce an unsupported description: property.
• High-precision business language: Each description provides meaningful business context without resorting to generic wording. The Skill uses concise business language to explain the relevant semantic behaviour of measures.
• Filter logic: Descriptions explain filter behaviour when relevant.
• Automated quality and encoding checks: After the documentation phase, the Skill runs automated checks across the modified project files to confirm that the required TMDL syntax and encoding standards have been maintained. This is described in more detail in the Validation, Encoding, and Structural Integrity Controls section.

Phase 2: Synonyms

Once the first phase has been validated, the Skill proceeds to synonym enrichment when culture files are present in the project.

These are some of the constraints applied when generating synonyms:

• Business-language focus: The Skill generates synonyms based on the terminology used by report consumers, analysts, and business stakeholders rather than relying solely on technical field names. This helps to align the linguistic layer with the terms users are likely to include in their questions.
• Enriching short or generic names: Synonyms are evaluated in the context of the semantic model, not in isolation. When a table or column name is short or too generic, the Skill doesn’t just restate the object name but enriches the synonym set with business context, linking the object to the specific process, data grain, analytical role, or business concept it represents.
• Precision over volume: The configured synonym limit is treated as a ceiling, not a target. The Skill prioritises high-value business terms over broad, generic lexical variants or technically correct but unnatural alternatives. If one or two precise terms are sufficient to map the field accurately, no additional terms are added.
• Strict curation and pruning: The Skill reviews the final synonym set, reducing ambiguity, redundancy, and unnecessary linguistic noise.

Once both phases have been executed, the generated metadata is written back to the semantic model. This enrichment can be verified directly within the Properties pane of the Model view, where the object descriptions and synonyms are fully populated without requiring manual entry:

Before enrichment: blank descriptions and default synonyms

After enrichment: generated descriptions and curated synonyms

Descriptions and Synonyms: Essential Metadata for Copilot in Power BI

The success of a conversational AI interface depends greatly on the quality and completeness of the model’s metadata. For example, when a sales director asks Copilot “How did our national customers perform this quarter?”, Copilot needs to understand the context of the data. If a table within the model contains a column with a technical name like Cod_Cli_Nac, detailed descriptions for tables, columns, and DAX measures help Copilot interpret the intended fields and business logic, reducing the risk of misleading or inaccurate answers.

This need is not limited to poor naming conventions. Even in optimal scenarios where a field already has a clear, business-oriented name (such as “National Customer Code”), a detailed description is still important. A clear label identifies what the field contains, but not how it behaves. These details are critical for AI tools to interpret business questions correctly.

This is where Phase 1 (Description-First) of the Skill plays a critical role, as descriptions provide grounding metadata that can guide the AI towards approved business definitions rather than assumptions based on object names alone. By clarifying the logic, scope, and context of the data, these descriptions can improve the relevance and consistency of natural-language responses, whilst synonyms complement them by adding the everyday linguistic variations that users may naturally include in their questions.

The Impact of Naming Conventions on AI Performance

Naming conventions are an important factor in the performance of conversational AI tools; column names like Cod_Cli_Nac add ambiguity and require additional contextual interpretation. The less closely a field name reflects business language, the greater the risk of misinterpretation or inaccurate results, and the linguistic layer must compensate through additional synonyms and more detailed descriptions. Best practice is therefore to use clear, self-descriptive, and business-oriented names from the outset.

The Challenge of Synonyms: Reverse Engineering

Automating the creation of Power BI Q&A synonyms in TMDL culture files is technically complex, primarily because Power BI separates standard model metadata from the linguistic layer used by Q&A.

• Object metadata: Standard properties such as descriptions are part of the tabular model definition and are exposed through the Tabular Object Model (TOM), linked directly to the definition of tables, columns, and measures.
• Linguistic layer: Synonyms are part of Power BI’s Q&A linguistic metadata. Although they are associated with model objects, they are not stored as standard object-level properties like descriptions. Instead, they are managed through the model’s linguistic schema, represented by linguisticMetadata, which is culture-specific and can be stored in TMDL culture files such as definition/cultures/en-US.tmdl.

Although Microsoft has announced that Power BI Q&A experiences and their associated tooling are scheduled for retirement in December 2026, linguistic metadata remains relevant to existing Q&A-enabled semantic models and to Copilot’s current Ask data questions experience, which still uses the underlying Q&A engine. The synonym-enrichment phase should therefore be understood as support for current implementations, while Microsoft’s longer-term direction for natural-language querying is Copilot for Power BI.

Modifying this layer programmatically requires manipulating deeply nested JSON structures, where, in this implementation, each synonym is accompanied by specific metadata, including a LastModified entry and a generation entry marking it as user-approved (“Source”: {“Type”: “User”}). Malformed JSON, incorrect TMDL indentation, or misplaced delimiters can cause parsing errors and prevent the project from opening.

To overcome this challenge, we followed an iterative reverse-engineering process with the AI coding agent:

1. A synonym was introduced manually through the Power BI Desktop interface.
2. The exact changes generated in the relevant .tmdl files were isolated and analysed.
3. This structural pattern was incorporated into the Skill logic, enabling it to locate the required sections, apply the modifications, and perform the corresponding validation checks.

As a result, the Skill could open, interpret, and modify the linguistic metadata reliably whilst preserving the structural integrity of the TMDL files.

Validation, Encoding, and Structural Integrity Controls

To ensure the reliability of the Skill, the automation does more than insert text into the model files. It follows a staged execution process based on model discovery, syntax validation, structural integrity checks, and strict encoding controls.

• Mandatory discovery phase: As described in Phase 1, the Skill reviews the model structure and dependencies before making any changes. This helps to ensure that the generated metadata reflects the semantic model accurately.
• Protection against character corruption (mojibake): The Skill uses controlled .NET-based read and write operations to read the modified TMDL files and write them back using UTF-8 encoding without a byte order mark (BOM), reducing the risk of character corruption when the project is reopened in Power BI Desktop:

Preventing character corruption (mojibake) in TMDL files

• Structural validation: After each execution phase, the Skill performs automated checks designed to reduce the risk of formatting and parsing errors when the project is reopened:
  • Syntax compliance: The Skill verifies that descriptions use the native TMDL triple-slash syntax (///) and that unsupported description patterns have not been introduced.
  • Description content checks: The Skill confirms that generated description entries are not blank; the relevance and accuracy of their content should then be reviewed against the approved business definitions.
  • Linguistic block integrity: The Skill validates the JSON structure, including bracket consistency and comma placement, to reduce the risk of malformed linguistic metadata.
  • Pruning and boundary control: The Skill evaluates the final set of approved and visible synonyms. If the curated synonym set exceeds the configured limits, the Skill removes the terms that are redundant, overly generic, ambiguous, or less relevant to the object’s business meaning, keeping the linguistic metadata concise and reducing ambiguity.

Conclusion

The Power BI Metadata Enrichment Skill demonstrates how a Skill can automate a substantial part of semantic-model documentation whilst applying repeatable syntax, encoding, and validation rules. The resulting workflow can improve developer productivity and strengthen metadata governance, provided that generated descriptions and synonyms are reviewed against approved business definitions.

Here at ClearPeaks, we are applying agentic AI to practical engineering workflows rather than treating it as a future concept. This implementation shows how reusable AI-assisted processes can raise documentation standards and prepare Power BI models for current natural-language querying capabilities.

If your organisation is looking to accelerate Power BI documentation, strengthen semantic-model governance, and prepare its models for AI-assisted analytics, contact us today to see how our expert team can help you!