Metadata enrichment
Answers to common questions about Context Agents Studio—covering enrichment behavior, collections, agent support, processing time, and AI 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.
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 AI credits?
Yes. Each agent run consumes AI credits based on the number of assets processed.
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.
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 with query history |
SQL Intelligence requires associated query history from connected data warehouse sources, so it applies to SQL assets only.
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'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 follows the 500 most popular assets in the collection—the ones a run can actually reach—rather than the collection total, so it can become unavailable while the coverage figure still shows a gap. For collections of 500 assets or fewer, the two match.
What happens when I run out of AI credits?
If your organization's 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 credits are replenished.
Contact your Atlan account team to add more credits.
How many assets can be enriched per run?
Each collection has an enrichment limit of 500 assets per agent run. When a collection contains more than 500 assets, the 500 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 500 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 500. See I re-ran an agent and nothing was enriched.
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 500 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 an agent enriches a table, it automatically enriches all child columns as part of that table. The asset count shown in a collection reflects parent assets only.
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.
Are 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 credits: 10 for the parent table and 10 for each of the 50 columns. Running the README agent on that same table costs 50 credits, because the README is generated for the table and not for its columns.
See Credit usage 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 500 most popular assets in the collection, and that limit is applied before the agent checks what still needs enriching. Once those 500 are done there's nothing left for a run to do, even when the collection is larger and unenriched assets remain below rank 500.
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 500-asset window of their own run.
Why didn't SQL Intelligence generate anything?
SQL Intelligence derives joins, filters, business questions, and foreign key relationships from query history. Where an asset has no query history, there's nothing to derive and the agent produces no insights for it. The run still completes successfully, because the agent 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
The agent doesn't fall back to lineage or column names—insights are only generated from queries that actually ran.
Assets that produce no insights aren't charged—only assets written back with insights count towards 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. 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. Reverse sync writes user descriptions to your source system, and doesn't read AI-generated ones. To push an AI-generated description back, open it on the asset, edit it, and save—that makes it a user description, which reverse sync then picks up.
Remove them in bulk: not self-serve today. Asset Import's Remove attributes, if empty option covers source and user descriptions, not AI-generated ones. Contact 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.
Custom instructions are also organization-wide. There's no per-collection or per-run instruction, and no template or worked-example input for descriptions. README templates are configured separately.
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
- Credit usage: Per-agent credit costs and coverage metrics
- Trigger AI enrichment: Step-by-step guide