Skip to main content

Agent design decisions

Connect docs via MCP

Context agents make specific design choices that may feel unexpected if you're optimizing for human readability. This page explains those decisions so you can set the right expectations with your team and get the most out of each agent.

Description agent​

Descriptions are verbose by design​

Descriptions generated by the Description agent are intentionally more verbose than a human writer typically produces. This is a deliberate design choice, not a quality issue.

Why verbose? Descriptions in Atlan are increasingly consumed by AI agents—for talk-to-data applications, operational workflows, and semantic search—not just by humans browsing the catalog. AI agents benefit from richer, more explicit descriptions: more context means fewer ambiguous inferences, more accurate query generation, and better answers.

Human readers tend to prefer concise descriptions. AI agents prefer verbose ones. Since descriptions now serve both audiences, the agent optimizes for the audience that's harder to serve: the AI.

What this means for your team

Verbose and correct is the goal. Verbose and incorrect is a problem worth fixing. If descriptions are factually wrong or include irrelevant details, use custom instructions to guide the agent toward your terminology and context.

Can you make descriptions less verbose?​

Yes—you can add custom instructions asking the agent to produce shorter descriptions. However, this isn't recommended. Governance teams and data consumers rarely converge on a "right" level of verbosity, and optimizing for human brevity reduces the utility of descriptions for AI downstream consumers.

If your primary use case is human discovery (not AI), adding custom instructions to adjust tone and concision is a reasonable trade-off.

README agent​

READMEs are human artifacts​

The README agent is optimized for human readers arriving at an asset for the first time. It summarizes the table's purpose, position in the pipeline, usage patterns, and broader context—all the things a person needs to decide whether this asset is relevant to their work.

In agentic use cases, READMEs may not be needed. An AI agent can consume schema, lineage, linked terms, tags, and SQL intelligence directly in a single pass. The README is a compressed, human-friendly version of what agents can already reconstruct from raw signals.

info

Generate READMEs for assets that humans regularly visit. Skip READMEs for intermediate or purely machine-consumed assets and invest that enrichment budget in descriptions and SQL intelligence instead.

Don't put dynamic information in READMEs​

READMEs get stale. Avoid capturing information that changes over time:

  • Downstream use cases—what reports or dashboards consume this table changes as the data estate evolves. Lineage in Atlan reflects this dynamically; a README describing downstream consumers may be wrong within weeks.
  • Refresh frequency—this belongs in a structured attribute, such as a custom metadata field, where it can be queried and kept accurate.
  • Row counts, current record ranges, or point-in-time statistics—these age out immediately.

A good README describes what the asset is and how it's meant to be used, not what's currently in it. For dynamic attributes, use custom metadata or let Atlan's lineage and column-level metadata carry that information.

SQL Intelligence agent​

What it analyzes today​

The SQL Intelligence agent derives usage patterns from two sources:

  1. Most popular queries—the agent analyzes the highest-frequency queries run against a table to surface common joins, filter conditions, and business questions being asked of the data.
  2. DDL command—the CREATE TABLE or CREATE VIEW statement used to define the asset, which reveals column relationships, foreign key hints, and structural intent.

From these inputs, the agent identifies:

  • Tables most commonly joined together
  • Frequent filter conditions (for example, WHERE region = 'US')
  • Inferred foreign key relationships between tables
  • Recurring business questions derived from query patterns

What's coming​

SQL Intelligence is expanding. Planned additions to the agent's input set include:

  • Larger query corpus—moving beyond the most popular queries to analyze a broader range of query history
  • Metrics and dimensions—explicit documentation of which columns function as measures vs. dimensions
  • Time frequencies—how the table is typically queried over time (daily, weekly, event-based)
  • Sample data—representative values to improve business-context inference
  • Data profiling—statistical summaries to surface distribution and cardinality signals
  • Data quality rules—linking active quality rules to the SQL patterns they protect

These expansions make SQL Intelligence progressively more useful as a standalone source of business context, not just a supplement to descriptions.

See also​