MotherDuck puts metric rules inside the warehouse—but shared agent context is still an operating process

MotherDuck has documented an internal problem created by successful self-service analytics: when more employees can ask agents to query the warehouse, access gets easier while agreement on what a metric means can deteriorate. In an Oct. 15 account, chief of staff Kaitlyn Henry says teams can independently construct retention analyses through the MotherDuck MCP server, but differences in grain, exclusions or revenue treatment can produce conflicting versions of the same metric (MotherDuck blog).

The company’s response is Guides, markdown documents stored in MotherDuck that describe definitions, trusted tables, joins, exclusions and known pitfalls. MotherDuck’s documentation says MCP-connected agents discover Guides through query, catalog-search and table-listing workflows, then fetch the relevant document before writing SQL. Guides can reference catalog objects, are grouped by topic and retain version history on updates (MotherDuck Guides documentation).

The control is context delivery, not deterministic SQL

This design separates the governed what from the generated how. An organization can specify that recurring revenue comes from a particular table at a particular grain, while leaving the model free to choose joins, common table expressions or window functions. That is useful because the business definition can remain reviewable even when generated SQL varies between sessions.

But a Guide is not itself a guarantee that every query is correct. MotherDuck’s own docs describe several discovery paths rather than a database constraint: the query tool nudges the agent to retrieve guidance, catalog searches return related Guides, and object references surface relevant documents. Operators therefore still need tests that show an agent selected the right Guide, interpreted it correctly and produced the expected result (MotherDuck Guides documentation).

Identity and ownership become part of metric governance

Visibility has two levels. Organization Guides are visible across the organization and require an administrator to publish; user Guides are private to their owner. The documentation adds an important service-account caveat: when several end users share one service-account identity, that account’s private Guides become shared context for those users, and a topic name is not an access boundary (MotherDuck Guides documentation).

That turns connection design into a governance decision. A multi-tenant application cannot safely assume that “private” means one human unless each tenant or user has an appropriately isolated identity. Teams also need an owner for central definitions, a review path for changes and regression questions that catch metric drift.

Henry’s internal process is telling: MotherDuck first used an agent to reverse-engineer a draft data dictionary from schema information, then had a small group resolve the business nuances the schema could not reveal. Her estimate was that the generated starting point was about half right; the rest required people to decide what concepts such as churn actually meant for the business (MotherDuck blog).

The practical lesson is not that markdown replaces a semantic layer. It is that enterprise agents need a governed route from business decisions to query-time context. Storing that context near the warehouse makes it easier for MCP-connected agents to find, but consensus, identity isolation and validation remain human operating responsibilities.