Data modelers are the only engineers still paying for their tools. Authoring should be free; hard-to-build infrastructure is what you should pay for. The layer that teaches an agent to use a semantic model - the skills and the MCP tools - is not a moat either. Nobody gets value from a semantic model until an agent can use one, so we gave it away; Kyle's post on why we did makes that case.
This post is the detail: what an agent actually needs from a semantic model, what we open-sourced to give it that, and the principles those pieces are built on. All of it lives in Malloy Publisher, the open source semantic model server for Malloy - the same code runs from npx on your laptop and from a container in production. Local development is the part no SaaS can give you, and it matters more than it used to: state-of-the-art coding agents like Claude are swinging the pendulum back from SaaS to local, because they work where the files are. A model you can run, edit and version on your own machine is one an agent can actually work on. Credible is our hosted platform built around Malloy and Publisher. If you would rather just get an agent building semantic data models and analyzing data, skip to the tutorial.
What an agent needs
Hand an agent a Malloy model and it does well. Building on a semantic model gives it an interface to your data. Malloy sources are what the interface is built from: a source is a table plus the joins, dimensions and measures declared on it, written down once. The implementation stays behind that interface, so the agent reads meaning from those definitions rather than inferring it from raw columns, and the questions you ask stay the same when what sits underneath them changes. The semantics rule out a class of errors that SQL leaves you to catch, like a join that quietly doubles a total.
Handing the whole model over works while it is small - context windows are large enough now that a basic semantic model fits comfortably. But fitting is not the same as being worth the space: a session fills with query results, follow-up questions and the agent's own reasoning, and every source you hand over at the start crowds out what it will need later.
Front-loading buys nothing anyway, because asking for additional context is cheap. You check a book's index rather than reading it cover to cover, and you search the web rather than reading it end to end. So the problem is not teaching an agent Malloy, and it is not capacity. It is handing it the right context and nothing more: the source and the measures and dimensions that answer the question. It also wants any views - queries saved on a source under a name - that already answer something close. Hand it too little and it hallucinates; hand it too much and it loses attention and is wasteful.
Selecting that context only works if your model has the same vernacular as the questions asked. Documentation is what closes that gap. It is not commentary: it is what a question resolves against, so that someone asking about revenue reaches the right definition, regardless of what it is named in the database. Writing a model that way is its own craft, which is why the modeling skills ship alongside the rest.
Knowing your model is a different thing from knowing how to analyze well. Scoping a question, the idioms that make Malloy powerful, the checks that make an answer trustworthy - that is craft, and there is far more of it than any agent should be handed at the start of a session. If all of that context is pushed in up front it buries what applies right now - instead skills load when they are relevant: guidance for the step the agent is on.
What we open-sourced
The tools
Five tools, reachable by any agent over MCP. Two of them find what to query, one runs it, and two more are for when the agent is writing a model rather than reading one:
getContext- what is in the model, narrowed to the question being askedsearchDocs- how to write the Malloy, from a bundled copy of the documentationexecuteQuery- runs the querycompile- checks an edit without running itreloadPackage- makes a saved edit queryable
getContext searches the semantic model, the same way a reader uses the index in a textbook or a search engine to navigate the web. Give it a plain-English question and you get back only the sources, views, dimensions and measures relevant to it, each with its description and metadata. The matching is semantic rather than textual: Publisher indexes the documentation a modeler attached to an entity alongside the entity's own name, which is how a question about "revenue" reaches a measure named total_sales, and why a well-documented model works better.
searchDocs is keyword search over a bundled index of the Malloy documentation, so the agent looks syntax up instead of guessing.
compile and reloadPackage are the authoring pair. The first validates a change and returns diagnostics without running anything, so an agent stops firing throwaway queries just to learn whether its edit parses; the second makes a saved change queryable without restarting the server. Together they let an agent iterate on a model, or on a data app, in watch mode.
The skills
Thirty of them: the query patterns, the SQL habits Malloy makes unnecessary, chart selection, and the analysis discipline that makes an answer trustworthy, plus the skills to discover, build, document, materialize and review a model. They are portable. Agents that load skill files natively (Claude Code is one) use them directly; agents that work over MCP get the same skills served as MCP prompts. One set of skills, any agent.
Why it is built this way
Our design principles are published alongside the skills, and they start from one assumption that decides everything else: tools are written assuming the skills are there too. Early MCP tools had to work standalone, so every response carried its own documentation, workflow guidance and interpretation hints. Invert that and a tool gets to be lean, returning domain data while the skills carry the reasoning.
The inversion buys a clean division of labor. Agents reason, skills guide, tools retrieve, and a tool never tries to infer intent: it does what it was told and returns what it found. It also means each piece of guidance lives in exactly one place. The same advice restated in the skill, the tool description and the tool response is three copies to keep in sync, and two of them bill you on every single call - context the agent no longer has for thinking. And a tool description is the interface an agent actually reads to decide whether to call something at all.
The places we knowingly break the rules are written down too. A design exceptions record sits beside the principles, and in a review, anything that diverges without being listed there is treated as a bug. An exception someone wrote down is a deliberate choice; an undocumented one is just the rules quietly eroding. Both documents live in the repo next to the code and change the same way it does - by pull request. If a principle does not hold up in your domain, open one and make the case.
Try it
The tutorial takes a few minutes: an agent answering real questions against a real model, and the commands to point one at your own. Later in this series we turn from querying a model to building one, from your own data or an existing LookML project.
If you are working on agents for your own domain, read the contributor guide, browse the skills or install them from npm. Join the Malloy Slack and tell us where they fall short. The model is the product, and the best way to make it better is in the open.
