Metadata enrichment
Answers to common questions about Context Agents Studio—covering enrichment behavior, collections, agent support, processing time, and Flexi Credit usage.
Common questions about how context agents work, what they support, and how enrichment is tracked.
Does AI overwrite my existing metadata?
No. Context agents only enrich assets that are missing the target metadata attribute. If an asset already has a description, README, or linked terms, the agent skips it. Existing values are never overwritten.
The one exception is keep fresh: it regenerates descriptions and READMEs that an agent wrote, on assets that changed since. Text a person wrote is never touched.
For descriptions, an asset counts as already described if it holds a description from any source—crawled from your source system, written by someone in Atlan, or generated by a previous agent run. A table carrying a Snowflake COMMENT is skipped even though nobody in Atlan has documented it. See Understand how descriptions are stored.
How long does enrichment take?
Enrichment can take up to a few hours for large collections (1,000+ assets). You can monitor progress live from the collection overview without leaving the page.
Do agent runs cost Flexi Credits?
Yes. Flexi Credits are counted per asset enriched, and the amount depends on the agent. Assets the agent skips, or produces nothing for, aren't charged. See How Flexi Credits work.
Why don't I see Popular BI Reports or Upstream of Popular BI collections?
These collections are only created when a supported BI source is connected to Atlan. If no BI source is connected, these collections don't appear.
Why don't I see ReX - MCP Usage Gaps in my workspace?
Atlan creates this collection only when your workspace had MCP usage in the previous 30 days. It builds the collection from the questions people asked through the Atlan MCP server, which is how AI tools such as Claude or Cursor connect to Atlan. If there were none in that window, there's nothing to build it from, so Atlan doesn't create it. Once people in your workspace ask questions through MCP, Atlan creates it on the next monthly run whose 30-day window includes that usage.
Only MCP conversations count: questions asked in Atlan's in-app AI assistant aren't included yet. ReX - Priority Enrichment doesn't depend on MCP usage, so you still get that one. See ReX collections.
Which sources are supported for each default collection?
| Collection | Sources |
|---|---|
| Popular SQL Assets | Snowflake, Databricks, BigQuery |
| Popular BI Reports | Power BI, Tableau |
| Gold Layer | BI + SQL sources |
| Upstream of Popular BI | BI + SQL sources |
| DQ Connected Assets | All sources with connected DQ tools |
| Assets with Owners | All sources |
| Assets with Product or Domain | All sources |
| Assets with Terms | All sources |
What assets does each agent support?
| Agent | Supported assets |
|---|---|
| Description | All asset types |
| README | All asset types |
| SQL Intelligence | Tables and views |
SQL Intelligence applies to SQL assets only. It builds from query history, so a table or view with none is still processed but produces no insights—see Why didn't SQL Intelligence generate anything?.
How often do collections refresh?
Default collections (Popular SQL Assets, Popular BI Reports, etc.) refresh periodically based on usage signals from your connected sources: query logs, lineage relationships, and BI usage data. They update automatically as your usage patterns change.
Custom collections refresh automatically when new assets match the collection's filter criteria—for example, when a new table is tagged with the tag your collection filters on. No manual action is required; the collection expands to include the new assets.
How often do ReX collections refresh?
Monthly, on the first of each month. Each run rebuilds ReX - Priority Enrichment and ReX - MCP Usage Gaps and replaces the previous month's membership with the new one. It's the same collection refreshed, not a new collection each month.
There's nothing to configure. Atlan builds the collections automatically, and building them doesn't use Flexi Credits. Agent runs you start on a ReX collection, and keep fresh, cost Flexi Credits as they do on any other collection. See ReX collections.
How's metadata coverage calculated?
Coverage % is the percentage of assets in a collection that have a given attribute filled in. For example, if 60 out of 100 assets have a description, the coverage for Description is 60%.
Coverage counts parent assets (tables, views, and BI reports), not their columns.
It also controls whether the Enrich Now button is available. The button becomes unavailable once either the whole collection reaches 100%, or the 1,000 most popular assets—the ones a run can actually reach—all have the attribute, whichever happens first. On collections larger than 1,000 assets, that means it can go unavailable while the coverage figure still shows a gap.
What happens when I run out of Flexi Credits?
If your organization's Flexi Credit limit is exceeded mid-run, the current enrichment run continues to completion—it won't stop mid-collection. However, once the limit is exceeded, you won't be able to start new runs until Flexi Credits are replenished.
Collections on keep fresh stop refreshing too: when a refresh costs more than the workspace has left, keep fresh pauses itself and shows Off · paused for credits until you turn it back on.
Contact your Atlan account team to add more Flexi Credits.
How many assets can be enriched per run?
Each collection has an enrichment limit of 1,000 assets per agent run. When a collection contains more than 1,000 assets, the 1,000 most popular are selected. Assets with equal popularity are ordered by name, so where no popularity data exists the order is effectively alphabetical.
The limit is applied before the agent checks which assets still need work. A run takes the 1,000 most popular assets in the collection, whatever state they're in, and enriches whichever of those are still missing the attribute—it doesn't look past rank 1,000. See Why did re-running enrich nothing?
Can I create my own collections?
Yes. Custom collections are available now. Click + New collection in Context Agents Studio to create one.
Filter assets using:
- Atlan-native tags: source-synced tags from connectors aren't selectable
- Custom metadata: first-level attributes only; nested boolean/enum filtering isn't yet supported
Tags with more than 10,000 assets are greyed out at selection time—custom collections are capped at 10,000 assets. Once created, run any agent—Description, README, or SQL Intelligence—on your custom collection. Each agent run processes up to 1,000 assets at a time.
Custom collections filter and count parent assets (tables, views, BI reports) only—not columns. You don't need to include columns in your filter. When the Description agent enriches a table, it also describes that table's columns; README and SQL Intelligence work at the table level only. The asset count shown in a collection reflects parent assets either way.
See Custom collections for full details.
Can I track additional metadata attributes beyond defaults?
Yes. Click + Track metadata in the collection detail view to add or remove the attributes shown in the coverage overview.
Who can use Context Agents Studio?
Users with the Admin or Governance Admin role can use Context Agents Studio—running agents, managing collections, and configuring settings. Other roles can view enriched metadata on assets but can't run agents or manage collections.
How does README agent choose which template to use?
When README templates are configured in Atlan, the agent evaluates all available templates and selects the best match for each asset based on its type, domain, and context. Template selection is automatic—you can't manually assign a template to a specific asset.
If no template is a strong match for an asset, the agent falls back to default README generation. Creating more targeted or domain-specific templates gives the AI better options to choose from.
In what order can I run agents?
Agents can run in any order, but the recommended sequence is:
- Description: Establishes per-asset semantic context first
- README: Can incorporate AI-generated descriptions as additional context
- SQL Intelligence: Independent of descriptions and READMEs, but benefits from existing description context
There are no hard dependencies. Running in a different order still produces good output.
What are custom instructions and how do they work?
Custom instructions let you guide agent output across your organization. They're configured in the Settings section of Context Agents Studio. Key things to know:
- Org-level only: Custom instructions apply to all agents and all collections globally—not per-collection or per-agent
- Plain text only: No markdown or rich formatting
- Prepended to all prompts: Your instructions are added to every AI prompt, shaping output across the board
Use them to reflect your organization's terminology, preferred description style, or business context the AI wouldn't otherwise have. For what an instruction can and can't refer to, see Can custom instructions reference any asset field?
Are Flexi Credits charged per asset or per child asset?
It depends on the agent. Only the Description agent enriches child columns, so only the Description agent charges for them. README and SQL Intelligence charge for the parent asset alone.
Example: Enriching a table with 50 columns using the Description agent costs 510 Flexi Credits: 10 for the parent table and 10 for each of the 50 columns. Running the README agent on that same table costs 50 Flexi Credits, because the README is generated for the table and not for its columns.
See How Flexi Credits work for how runs are charged, and Flexi Credits rate card for full pricing details.
Coverage shows 100% but my columns are empty
Coverage counts parent assets—tables, views, and BI reports—not columns. When every table in a collection has a description, coverage reads 100% even if none of the columns underneath do.
Because coverage also controls the Enrich Now button, a collection in this state shows the button as unavailable for that attribute.
The enrichment itself does cover columns: when the Description agent runs on a table, it writes descriptions for the table's columns as well. If your tables are already described and only the columns need work, contact Atlan support.
Why did re-running enrich nothing?
Each run works on the 1,000 most popular assets in the collection, and that limit is applied before the agent checks what still needs enriching. Once those 1,000 are done there's nothing left for a run to do, even when the collection is larger and unenriched assets remain below rank 1,000.
What you'll see is Enrich Now unavailable while the collection still shows a coverage gap.
Split the collection into smaller collections so the assets you want reached fall inside the 1,000-asset window of their own run.
Why didn't SQL Intelligence generate anything?
SQL Intelligence builds entirely from query history. Where an asset has none, there's nothing to derive: the agent produces no insights for it and doesn't substitute lineage or column names instead. The run still completes successfully, because the agent itself ran as expected.
Common reasons an asset has no query history:
- The query history or miner workflow isn't configured for that connection
- The source doesn't support query-history mining in Atlan
- The table is new, or genuinely isn't queried
Where queries do exist, business questions, joins, and filters each trace back to a specific query. Foreign key relationships are inferred more broadly: alongside the joins observed in queries, the agent also weighs declared key flags, column lineage, and naming conventions.
Assets that produce no insights aren't charged—only assets written back with insights count towards Flexi Credit usage.
If the assets you're asking about do have visible query activity, check the Intelligence tab on the asset, which is where SQL Intelligence output appears. If it's empty there too, contact Atlan support.
Which description displays first?
An asset can hold a source description, a user description, and an AI-generated description at the same time. Atlan displays the first one present, in this order:
- User description
- AI-generated description
- Source description
An AI-generated description therefore appears ahead of one crawled from your source system. Asset cards in a lineage graph are the exception: they don't show a description at all.
See Understand how descriptions are stored for what happens when you accept or edit a suggestion.
Can I export AI-generated descriptions, or push them to my source system?
Export: yes. Asset Export (Advanced) includes an AI Generated Description column. Asset Export (Basic) doesn't.
Push back to the source: not directly, and only Snowflake is supported. The Asset Description Reverse Sync workflow writes your team's descriptions back as Snowflake comments; it doesn't read AI-generated descriptions, and it doesn't cover other sources. To push an AI-generated description back, open it on the asset, edit it, and save—that makes it your team's description, which the workflow then picks up on its next run. It syncs recent changes rather than reconciling everything, so edit the descriptions you want synced rather than expecting a backfill of older ones.
Remove them in bulk: not self-serve today. In Asset Import, setting Options to Advanced reveals Remove attributes, if empty, and that list covers Description (system) and Description (user), but not AI-generated descriptions. Contact Atlan support if you need AI-generated descriptions cleared across many assets.
Can custom instructions reference any asset field?
No. Custom instructions can only act on the information the agent already receives—asset names, schema, lineage, query history, and your glossary. An instruction that refers to a field the agent isn't given has nothing to act on.
There's also no template or worked-example input for descriptions. README templates are configured separately, and the scope of custom instructions is covered in What are custom instructions and how do they work?
See also
- Collections: How default collections are built and populated
- How descriptions are stored: The three kinds of description and which one displays
- Context agents: What each agent generates and which assets it supports
- How Flexi Credits work: How agent runs consume Flexi Credits, and where to track usage
- Flexi Credits rate card: Flexi Credits used by each agent and Atlan AI capability
- Trigger AI enrichment: Step-by-step guide