I built an MCP server so AI agents can find and query our company data. Most of my time did not go into the server. It w...

I built an MCP server so AI agents can find and query our company data. Most of my time did not go into the server. It went into one question: why does the agent pick the wrong table?The answer is almost always the dbt docs. Here is what I learned. 1. The agent only sees the start of your descriptionWhen I indexed our dbt models for search, I could not embed everything. Long text gets cut. So only the first line of a model description and the first two sentences of each column count.Everything after that never reaches the search. Put the point in sentence one: what this table is, at what grain, and what it is not. Same for NULLs. If a column is null for a special reason, say it in the first sentence. 2. Never let AI write your YAML from the modelThis is the biggest trap. You have 300 models, no time, so you ask an AI to write the descriptions from the SQL.You get things like user_id: Identifier of user.That says nothing. The agent can already see the column is called user_id. What it n...