Do this with AI
Install the dx-mcp-server skill from Contentstack agent skills and connect the Content Explorer profile in MCP Profile Hub. Then ask your agent:
List the content types, locales and branches your tools know about for my stack, then show me the fields you would expect when reading a blog_post entry.
New to this? Set up your AI workbench first.
How MCP Profile Hub enriches tools for your stack
When you connect an AI agent to a profile in MCP Profile Hub, the tools it gets back from tools/list already know your stack. The content_type_uid argument lists your content types. The branch argument lists your real branches, and it only gets a default when the profile sets one. We built this into Profile Hub, and in this post I explain how it works, what can go wrong, and what it costs in tokens.
The short version
On tools/list, Profile Hub patches generic tool schemas with enums, descriptions and context from the account you connected. The API request behind each tool doesn't change.
It enriches CMS, Launch, Brand Kit, Personalize and Developer Hub tools, per product, and only for the products the profile uses. A product that fails doesn't take the others down.
It works inside an 8-second budget, caches for 5 minutes without tokens in the cache key, and falls back to the generic definitions if anything fails.
In our evaluation it cut tool calls from 48 to 18 and latency from 159s to 105s, for about 3,700 extra tool-definition tokens per request.
The public tool definitions carry optional x-enrich keys, so you can do the same thing in your own runtime, or ignore them.
The problem with generic tools
Say you ask an agent to fetch the latest products. It calls a get-entries tool with content_type_uid: "product". Your stack doesn't have a product content type. It has guide, blogpost and page.
The call fails, so the agent lists the content types, picks one, and retries. That's three round trips for a request that needed one.
The model did what the schema told it to. The description said a content type UID looks like product, so it sent product. You see the same detour with environments, locales, branches, Personalize audiences and Brand Kit voice profiles. Any argument that takes an account-specific identifier makes the model guess.
What changes in tools/list
When your MCP client sends tools/list, Profile Hub reads the relevant values from your connected account and patches the input schemas before it returns them. The stored definitions stay generic. Only the copy your client receives carries your account's values.
This is the content_type_uid and locale part of a get-entries tool before enrichment:
{
"content_type_uid": {
"type": "string",
"description": "A content type UID, for example product."
},
"locale": {
"type": "string",
"description": "The locale code of the entries to fetch."
}
}And this is the same part for a stack with three content types and two locales:
{
"content_type_uid": {
"type": "string",
"enum": ["guide", "blogpost", "page"],
"description": "A content type UID. Stack content types: guide (Guide), blogpost (Blog Post), page (Page)."
},
"locale": {
"type": "string",
"enum": ["en-us", "fr-fr"],
"description": "The locale code of the entries to fetch. Stack locales: en-us, fr-fr."
}
}The locales here are an example. Your stack's values are what you get.
With an enum, the model can only pick a value that exists. Tool descriptions get the same context, with one rule to keep the cost down: when the tool already has the matching parameter, the description gives the count and points at that parameter instead of repeating every value. Otherwise every tools/list response would carry each list twice.
Lists are also bounded. An enum holds at most 50 values. When a stack has more, the description says the list was truncated and tells the agent which list tool returns the complete set.
If the profile sets an environment, locale or branch, that value becomes the schema default. That is how a profile scoped to one stack and one locale stops the agent from asking which one you meant.
Why defaults get removed
Enrichment also removes schema hints that are wrong for your account.
All 37 branch-aware tools used to declare main as their default branch. Some stacks don't have a main branch, or renamed it. A client that respects the schema sends branch=main to those stacks and gets a 422. In a trace that looks like a model error, but the model only followed the default it was given.
Profile Hub now removes that inherited default unless the profile sets a branch on purpose. The branch argument still gets an enum of the stack's real branches, just no default. What I took from this bug is that models treat the schema as the interface. Defaults, examples, enums and descriptions all change what the model sends, so each of them has to be correct for the account the agent is working in.
What gets enriched per product
A profile can mix tools from several Contentstack products. Profile Hub enriches each product separately:
Product | Enriched values |
|---|---|
CMS (Delivery and Management) | Content types, environments, locales, branches |
Launch | Projects and environments |
Brand Kit | Voice profiles and Knowledge Vault content |
Personalize | Attributes, audiences, experiences, events |
Developer Hub | Marketplace apps and organization |
Safeguards in production
Enrichment runs inside tools/list, so every client connection waits for it. If it were slow or fragile, every profile would feel slow or fragile. These are the safeguards that keep that from happening:
Time budget. Full enrichment gets 8 seconds. A slow product can't block tools/list past that.
Short cache. Results are cached for 5 minutes, and access tokens are not part of the cache key.
Request coalescing. Concurrent identical requests share one lookup instead of calling the same APIs in parallel.
Per-product failure isolation. If the Personalize lookup fails, your CMS and Launch tools are still enriched.
Fallback. If enrichment fails completely, you get the generic definitions. Every tool still works, with less context.
Clean output. The x-enrich keys that drive enrichment are stripped before the definitions reach your client, so the model never sees them.
What it costs in tokens
Bigger enums and longer descriptions make tool definitions bigger, so we measured whether that pays off. We ran 18 CMS tasks three times each against 77 Content Management API tools, once with enrichment and once without. These are the low reasoning effort results:
Metric | Generic | Enriched | Change |
|---|---|---|---|
Tool calls | 48 | 18 | 62% fewer |
Latency | 159s | 105s | 34% lower |
Reasoning tokens | 871 | 168 | 81% fewer |
Tool-error runs | 6 | 3 | 50% fewer |
Tool-definition tokens per request | 10.0k | 13.6k | 37% more |
The last row is the cost: about 3,700 extra tokens per request. Across the run, the agent made 30 fewer tool calls and finished 54 seconds sooner. A prompt like "entries from the content type that stores blog posts" went from nine calls to one, and counting entries went from sixteen calls to one.
We also included control prompts for areas enrichment doesn't touch, such as assets, taxonomies and releases. Those showed no difference, which tells us the gains come from the added context and not from run-to-run noise.
Caveat: About 93% of prompt tokens were cache hits, so the raw prompt-token totals say little about real cost. Watch tool calls and latency instead, because a cache hit doesn't save you a round trip.
For how we test agent behavior on profiles in general, read we don't test our MCP profiles, we test the agent.
Reasoning effort made it slower
We ran the same tasks at high reasoning effort. Enrichment still helped (tool calls went from 66 to 43, latency from 258s to 194s), but high effort was slower than low effort in both variants. It was also the only setting that failed a task: it distrusted a correct result and checked content types one at a time until it hit the turn limit.
For bounded CMS work with enriched tools, low effort did better. The full numbers are in part 3 of my Profile Hub series.
Profiles narrow the catalog, enrichment adds context
A profile decides which tools the model sees. A content editor's profile might have entry search, content model inspection and a few safe updates, while a release manager's profile has environments, releases, branches and deployments. With fewer tools to choose from, the model picks the wrong one less often. I explain why the profile is the right unit of configuration in part 2 of the series.
Enrichment then gives each of those tools your account's real values. A small profile with generic tools still sends the agent off to look up identifiers, and a large catalog with enriched tools still leaves it searching for the right tool. You need both to get short, correct traces. That's the same argument I made in build context-aware MCPs, not API wrappers.
Doing this in your own runtime
Contentstack publishes the tool definitions behind Profile Hub at public, unauthenticated endpoints, one per catalog, at https://mcp.contentstack.com/<catalog>/tools. They contain metadata only: names, descriptions, input schemas and request mappings. You bring your own tokens.
curl -s https://mcp.contentstack.com/cda/tools | jq 'keys'The definitions can carry three optional extension keys:
Key | Where it lives | What it tells your runtime |
|---|---|---|
x-enrich | On a property in inputSchema.properties | Patch this argument's enum, description or default |
x-enrich-description | On the tool | Append account context to the tool description |
x-enrich-group | On the tool | Apply a named set of property rules instead of repeating them per field |
None of these keys change how a tool call maps to an API request.
If you don't want enrichment, strip every key that starts with x-enrich before you pass the tools to your model. Every tool works with standard JSON Schema. If you do want it, fetch the values from the account, patch the marked properties, and then strip the keys. Copy the safeguards as well: a time budget, a short cache without tokens in the key, per-product isolation and a fallback to the generic schema.
The guide on building your own MCP server with Contentstack's tools API shows how to fetch and execute these definitions. Enrichment is one extra step in your tools/list handler on top of that.
Concluding
Profile Hub does the account lookups once, when the client asks for tools, instead of letting the agent repeat them in every conversation. It also removes defaults that would send the agent to a branch that doesn't exist. In our runs that cost about 3,700 tokens per request and saved 30 tool calls and 54 seconds, and I'd take that trade for any CMS profile.
The background, the profile model and the reasoning-effort results are in my three-part series: stop making the agent ask, one MCP server is the wrong abstraction, and when more reasoning makes the agent worse.
Frequently asked questions
What does enrichment change in an MCP tool?
Only the schema the model reads. Profile Hub adds enums, descriptions and context from your connected account to tool arguments on tools/list, while the underlying API request stays exactly the same.
What happens if enrichment fails or is slow?
Profile Hub isolates failures per product and works within a time budget. If enrichment fails entirely, you get the generic tool definitions and every tool still works.
Does enrichment make prompts more expensive?
Tool definitions grew by about 37 percent, roughly 3,700 tokens per request, in our evaluation. That cost was repaid by 62 percent fewer tool calls and 34 percent lower latency at low reasoning effort.
Can I use enrichment if I build my own MCP server?
Yes. The public tool definitions can carry optional x-enrich extension keys that describe which arguments to fill. A runtime that ignores them still works with the standard schemas.