by

Boosted AI agent performance by retooling models

A team at a Fortune 500 company was developing a series of interrelated data models. These data models would drive the product UI, including an AI agent that was key to product adoption and retention. But the data model content — API names and descriptions — didn’t meet standards that would provide good context for the LLM that powered the agent. I made a major improvement in LLM context for the agent by rewriting the content to clearly represent the model’s inherent structure and relationships. 

AI-ready data modeling
UX writing & content strategy

Results

25%

LLM context improvement at release

The situation

Agent performance depended on the data model

The models the team was developing would support agents that answered questions using an organization’s own structured data — such as schedules, records, current status — and could take action based on that data, like processing a request or scheduling something on a user’s behalf. The agent’s performance depended on how clearly the underlying model represented that data.

The Challenge

The structure and relationships inherent in the model weren’t clear 

Good API naming is sometimes treated as cosmetic. But in large or growing models, poor naming is more than a style problem. 

If the names and descriptions in a model aren’t perfectly clear, AI is happy to take a stab! But guessing can lead to hallucination, SQL problems, and degraded search. 

The names and descriptions that an engineering team drafts can make a solid start. But settling for them as final can make product performance and maintenance suffer later. Garbage in, garbage out.

I needed my team to collaborate with me on a thorough review of model content, and show them that this wasn’t extra overhead — it was the fastest path to a model that would perform as planned.

“Cate made linguistics and design principles a foundation of her work, resulting in productive discussions and outcomes based on something more solid than opinion.”

Lead Member of Technical Staff, Fortune 500 Company

My approach

I reviewed fields against three criteria, iterating with engineering and product management to resolve questions. 

While I worked through these content details, my goal was to bring the big picture into focus: How the model’s structure and relationships represented the product’s workings. 

1. Expose the structure and relationships in the model by writing unambiguous, mutually exclusive names

For every field, I asked: Do this name and description clearly state what the field does, and do they clearly distinguish it from every other field in the model? 

I made generic labels specific, so that a user or agent couldn’t confuse a field with another regardless of the context where it appeared. 

A planned field in a data model

A row in a spreadsheet showing a planned field in a data model, with column headers indicating draft or approval. "Approved" cells have green background: API name draft is Type. API name approved is UserRole. Description draft is The type of user. Description approved is The permission level assigned to the user: owner, admin, member, or viewer.

Compared to the name Type, the final API name for this field, UserRole, will make the field’s purpose easier to understand when it appears alone or alongside other fields.

2. Reinforce clarity by ensuring consistency

The same inconsistencies that confuse a human reader (is “Username” the same as “Account ID”?) can make AI hallucinate.

In a separate pass, I looked across objects in the model to make sure that:

  • The same word was used for the same concept everywhere
  • Naming patterns were applied across related objects
  • Descriptions gave a comparable level of detail throughout

The UI is another source of context

API names and technical descriptions provide context for the way a product handles data on the back end. 

When a product has a UI, that interface also provides context. Agents can use this context — in parallel with the data model — to understand how users interact with the product. 

When writing UI text for a product, I apply similar criteria to what I’ve outlined here — plus others; see [planned case study of UX writing for a released product]. 

3. Compromise

Once an API ships, renaming a field risks breaking existing integrations. For fields where the ideal name conflicted with something already released, the team and I had to weigh consistency with the existing pattern against the clarity of the new one. We took educated guesses at the future impact of our choices. 

“Cate brought order and predictable repetition to a complex job.”

Product Leader, Fortune 500 Company

More ways to improve the process

Today, I’d use AI to flag inconsistent naming and surface similar fields for review faster — but LLM context and agent performance still need a human with linguistic expertise making the final call. AI knows the past; it doesn’t know what a team will need to build next.