Make Your Content Model Agent-Friendly

When an AI agent works with your Agility instance through the Agility CMS MCP Server, it doesn't see your editor's form the way a person does. It reads your models as data: model names and descriptions, field names, types, labels and settings. Then it decides what to write. A model that's clear to that reader gets better content from agents, and better content from new editors too.

This page lists what agents read, and seven rules for making it useful.

What an agent sees

When an agent calls get_content_model_details or get_component_model_details, it gets the model as JSON. Here is a real model from the Agility docs instance, the Link model behind the docs site's navigation menus (the list of choices is shortened):

{
  "displayName": "Link",
  "referenceName": "Link",
  "description": "Defines a simple link.",
  "fields": [
    { "type": "Link", "name": "Link", "label": "Link", "required": true },
    {
      "type": "DropdownList",
      "name": "Icon",
      "label": "Icon",
      "description": "Brand/logo icon shown beside this link in the nav dropdown (frameworks, SDKs, APIs). Leave blank to auto-detect from the link text.",
      "copyAcrossAllLanguages": true,
      "required": false,
      "choices": [
        { "label": "Next.js", "value": "nextjs" },
        { "label": ".NET", "value": "dotnet" },
        { "label": "Content Fetch API", "value": "content-fetch" }
      ]
    }
  ]
}

Everything in it is a signal the agent uses: the model's description, each field's name, label, type and description, whether it's required, the allowed choices of a Drop-down List, and whether the value is constant across languages. The same details include a field's maximum length and validation pattern, the text of a Custom Section, and the list a Linked Content field points at. The Icon description above tells an agent where the value appears and when to leave it blank; without it, the agent would have to guess.

The model tools that create and update models accept a description for the model and for each field, so an agent can also write them for you.

1. Describe every model

Write a one or two sentence description for each Content Model and Component Model: what it's for, and when to use it instead of a similar model. "Defines a simple link" tells an agent nothing it couldn't read from the name. "A navigation link with an optional icon. Use for header and footer menus; use Call to Action for buttons inside page content" lets it choose correctly.

2. Describe the fields that need judgment

A field called Summary could be one sentence or three paragraphs. Use the field's description to say:

• What goes in it: "One sentence, under 160 characters, shown on listing cards and in search results."
• The format: plain text, Markdown, HTML, a URL, an ID.
• An example: "For example: How to publish a page and its nested content in one step."
• What not to do: "No marketing superlatives. Don't repeat the title."

You don't need a description on Title. You do on anything where two reasonable people would fill it in differently.

3. Use clear, stable reference names

Agents use reference names to find models and lists, to write Linked Content values and to write code. Make them easy to get right:

• Name for meaning. EventSpeakers, not List2. StartDate, not Date1.
• One convention. PascalCase for models, containers and fields is the safest choice, because the APIs return field names with the first letter lowercased (StartDate becomes startDate) and an initial acronym reads oddly (URL becomes uRL). Use only letters and numbers: GraphQL replaces any other character in a container's name with _.
• Don't rename casually. Code, queries and agent notes all depend on these names.
• Record them. Keep model, container and field names, with their IDs, in an instance ledger in your project's AGENTS.md, so agents start from facts. See Writing an AGENTS.md for Agility Projects.

Reference name case matters when writing: the read API returns reference names lowercased, but a User Selectable Linked Content field must be saved with the container's exact case. See MCP and Agility Gotchas to Know Before You Build.

4. Keep models small and single-purpose

An agent filling a model with 40 optional fields has to decide which ones apply, and it will sometimes fill fields that should stay empty. Smaller models with a clear job are easier for an agent to complete correctly, and easier for a reviewer to check. See Content Modeling Anti-Patterns.

5. Turn rules into validation

Validation is part of the model, so an agent reads it as instructions, and editors who review the content work with the same rules in the form:

• Required on fields that must be filled.
• Maximum length on titles, summaries and other fields with real limits.
• Regular expression validation with a clear message for formats such as product codes or slugs. See Advanced Field Validation with Regular Expressions.
• Drop-down List choices instead of free text wherever your code depends on the value. The agent sees the allowed values, as in the Icon example above.

A rule that only lives in a style guide is a rule the agent can't see.

6. Use Custom Sections for instructions

A Custom Section field shows a block of text in the editing form and isn't part of the content. The model details return its text, so it reaches agents as well as editors. Use one at the top of a complicated model for the rules that apply to the whole item: "Write the body in Markdown. Start with one H1. Images must be uploaded to the media library first."

7. Make relationships obvious

• Label Linked Content fields with what they point at: "Author (from Authors)", not "Related".
• Keep companion field names conventional (Author_ValueField, Author_TextField), so an agent recognizes them as the storage for a selection rather than as fields to fill in by hand.
• Prefer shallow structures. Each level of nesting is another set of calls for the agent to get right. See Nest, Link or Share?

Test it with an agent

Before you rely on a model, connect an agent through the MCP server and ask it:

1. "Describe the Event model. When would you use it, and what goes in each field?" If the answer is wrong, the model's descriptions are the fix.
2. "Create one sample item in Events." Then read the item back and check each field against what you expected.
3. "Which fields would you have filled differently with more guidance?" Agents are good at pointing out ambiguous fields.

Remember that saves through the MCP server go to Staging. Nothing the agent writes is live until it is published.

Put project-level rules in AGENTS.md

Some rules belong to your project rather than to one model: which models agents may write to, the publishing level your team allows, naming conventions for new models. Put those in your AGENTS.md, along with the gotchas from MCP and Agility Gotchas to Know Before You Build.

Related

• Agility CMS MCP Server
• Writing an AGENTS.md for Agility Projects
• MCP and Agility Gotchas to Know Before You Build
• Content Modeling Anti-Patterns
• Fields