Metric definitions in tooltips beside the number

The data dictionary was 41 pages, in a shared drive, in a folder called Governance. It was accurate, it had been written carefully over about three days, and the access log showed it had been opened eleven times since it was created, seven of those by the person who wrote it.

Meanwhile the report it documented was opened around ninety times a week.

Metric definitions in tooltips are the response to that ratio. The definition needs to be where the number is, at the moment somebody is looking at the number and wondering what it counts, because that is the only moment they will ever want it.

Where does a definition actually get read?

At the point of use, by somebody who has a specific doubt, in under about ten seconds. Outside that window, definitions are not read at all.

Gebru and colleagues made a version of this argument for machine learning data in Datasheets for Datasets, published in Communications of the ACM in December 2021. Their proposal is that a dataset should travel with its own documentation in the way an electronic component travels with a datasheet, so that the person consuming it gets the provenance without having to go and find it. The argument transfers directly. A measure is a small artefact that gets consumed constantly by people who did not build it, and documentation that lives somewhere else is documentation that does not travel.

The failure is not that teams refuse to document. Most teams document more than they need to. The failure is that the documentation and the number end up in different places, and only one of those places has ninety visits a week.

Who can actually see the description property?

Every serious modelling tool has a description field on a measure, and setting it is the right first step. What it does is narrower than most teams assume, and getting this wrong is why so many models are documented and so few readers benefit.

Microsoft's guidance on measure descriptions, published on Microsoft Learn and dated May 2026, states the reach precisely: "People building reports from your semantic model can see the name and description of your measures, making the description property essential documentation." Its responsible AI notes for the same feature go further, saying that "report authors can only see the name and description of a measure when determining which measure to use in their report."

Report authors. Not report readers. The description lives in the Fields pane, which is a surface only somebody in edit mode ever opens.

That is still worth doing, and doing thoroughly, because the author choosing between three plausible measures is exactly the person whose mistake propagates furthest. A description that says which population the measure counts stops the wrong one being dragged onto a canvas. It just does nothing whatever for the show director reading the finished page.

What the reader gets is a report page tooltip

The mechanism that reaches a consumer is a separate one. Microsoft's documentation for report tooltips, dated March 2026, describes it: you build an ordinary report page, set its page size template to Tooltip, turn the Tooltip slider on in Page Information, and drag the fields it should appear for into the Tooltip fields well. Then, in the documentation's words, "When you hover over a visual that includes the selected field, the tooltip appears and filters by the data point where your mouse is hovering."

A tooltip page can hold anything a report page can hold, which is both the opportunity and the trap. Teams discover this and build tooltips containing three charts and a table, which takes two seconds to render and covers a third of the screen.

For a definition tooltip, the right content is four short lines of text and nothing else. Population. Filter. Source system and table. Date the definition last changed. Set the canvas small, around 320 by 200, so it behaves like an annotation rather than a second report.

The last change date is the line people leave out and it earns its place more than any of the others. A reader who remembers the number behaving differently last quarter has an immediate answer, and a reader who is about to compare this quarter with a period before the change has been warned.

Twenty-six measures, documented in under two hours

The model behind the weekly show pages had 26 measures that appeared on a tile or an axis somewhere. Everything else was an intermediate.

Writing four lines for one measure takes about four minutes once you have the pattern, including looking up the source table to be sure. Twenty-six measures at four minutes each is 104 minutes. One afternoon, with a break.

Compare that with the 41 page dictionary, which took three days. The tooltip version is roughly a fifth of the effort and it is read by everybody who hovers, which on the pages in question turned out to be a few hundred times a month once people learned it was there.

Two implementation notes from doing it. Write the description on the measure first, then copy it into the tooltip page, so the two cannot drift; better still, drive the tooltip text from a small documentation table in the model so there is exactly one copy. And build one tooltip page per family of measures rather than one per measure, since a single tooltip page can be bound to several fields and 26 tooltip pages is an unmaintainable report.

The measures whose definitions took longest to write were the three nobody could agree on, which is the same pattern as writing the tile labels: the documentation exercise finds the disagreements rather than causing them.

What belongs in the four lines, and what does not

Population, filter, source, change date. Keep the whole thing under about forty words, because a tooltip that needs scrolling has failed and the reader will not scroll anyway.

Population is the noun. Professional attendees. Exhibiting companies with a signed contract. Registrations excluding cancellations.

Filter is what narrows it, written in the reader's language rather than as a formula. Excludes exhibitor staff and contractor badges is useful. A DAX fragment is not, and pasting the formula into the tooltip is a common shortcut that trades a definition for a specification.

Source is the system and the table, named as the operations team names them. This is the line that lets a reader escalate usefully, because the first question anybody asks after doubting a number is where it came from.

Change date is the date the definition changed, distinct from the date the data refreshed. The two get conflated and they answer different questions.

What does not belong: the business rationale, the history of the disagreement, the name of the person who owns it. Those are real and they belong in the governance document, which the tooltip can name in five words so anyone who needs it knows it exists.

Written out for one measure, the whole thing looks like this. Population: professional attendees, unique per edition. Filter: entry scans only, excludes exhibitor staff and contractor badge types, excludes badges scanned before the public opening time. Source: fact_badge_scan in the warehouse, loaded nightly from the access control platform. Definition last changed 14 March 2026, when contractor badge types were excluded.

Thirty-eight words, four lines, and it answers the four questions a doubting reader has in the order they occur to them. It also does something a longer document never manages: because the change date is right there, the reader comparing this edition with the one before knows immediately that the two are on different bases, and can go and ask what the exclusion was worth before quoting a variance. On this show the contractor exclusion moved the figure by about 1,100, so a year-on-year comparison built across that date and taken at face value is wrong by roughly 4 per cent in a direction nobody intended.

Where this stops

Report page tooltips have three limits worth knowing before you build a programme around them, and Microsoft's own documentation names all three.

They are not interactive. In the documentation's words, "Report tooltips aren't interactive", so a reader cannot select anything inside one, scroll it, or follow a link out of it. A definition tooltip that ends with go here for more is offering something the reader cannot take.

They are invisible to screen readers. The same page states that "Screen readers can't read report tooltip content when the tooltip appears for a data point in a visual or from the Help tooltip icon." If your reporting has to meet an accessibility standard, a tooltip cannot be the only place a definition exists, and the honest design is a definitions page that carries the same four lines in readable text.

They do not work everywhere. Dashboards do not support report page tooltips, and neither do some visual types. A definition strategy that assumes hover works on every surface will have gaps exactly where content gets pinned for executives.

There is a fourth limit that is not Microsoft's fault. A tooltip explains what a measure claims to count. It cannot tell the reader whether the measure does what the description says, and a well-documented wrong measure is a confident wrong measure. Pairing the tooltip with a path to the rows behind the number is what turns a claim into something checkable, and doing the naming work at the same time stops the reader needing the tooltip for the easy cases.

Pick the three measures your team argues about most this week and write four lines for each. Set the description on the measure, build one tooltip page, bind it to those three fields, and publish. It is under half an hour of work, and it is the fastest way to find out whether anybody in your event business intelligence audience actually hovers before you invest an afternoon in the other twenty-three.