Skip to main content

Write effective custom instructions

Connect docs via MCP

Custom instructions let you give Context Agents Studio organization-specific context that the AI has no other way to know. A blank instruction field means the agent relies solely on what it can infer from your metadata—table names, lineage, and query history. Adding even a few sentences of organizational context measurably improves description quality.

Custom instructions are org-level: whatever you write applies to every agent run across every collection. They're prepended to the AI's context for all enrichment activity.

Where to find custom instructions​

  1. From the left sidebar in Atlan, click Governance → Context Agents Studio.
  2. Click the Settings icon (gear) in the top-right corner.
  3. Enter your instructions in the Custom instructions field.
  4. Click Save.

What to include​

Company context​

Start with one or two sentences describing what your company does and the domain your data covers. This grounds every description the agent writes in a meaningful business context.

Example:

Acme Corp is a financial services company focused on retail lending. Our data covers loan origination, credit risk, portfolio performance, and customer lifecycle.

Domain and team structure​

List the key domains or teams that own data in your catalog, with a brief description of each. This helps the agent correctly attribute tables to their business area—especially when teams use similar naming conventions.

Example:

Key domains: Risk (credit scoring and loan default models), Finance (GL, revenue recognition, FP&A reporting), Operations (loan servicing, payment processing), and Marketing (acquisition campaigns, customer segmentation).

Internal abbreviations and naming conventions​

If your table and column names use internal abbreviations, acronyms, or shorthand that wouldn't be obvious to an outsider, list them with their meanings. This is one of the highest-value things you can add—agents frequently produce generic descriptions for columns with cryptic names when abbreviations aren't explained.

Example:

Common abbreviations: acct = account, cust = customer, bal = balance, orig = origination, pmt = payment, lgd = loss given default, pd = probability of default, mob = months on book.

Multiple languages​

If your organization operates in multiple languages or if metadata must be documented in a language other than English, specify this explicitly.

Example:

Generate descriptions in both English and Spanish. Use formal register for both languages.

Tips for better instructions​

  • Be specific, not exhaustive. Three focused sentences about your business context outperform a lengthy paragraph of generic filler. The agent reads your instructions every time—keep them signal-dense.
  • Focus on what the metadata can't show. The agent already sees table names, schemas, lineage, and query history. Instructions add what the data itself can't reveal: business purpose, organizational structure, internal terminology.
  • Update as your org evolves. If your team structure changes or you add a new data domain, update your instructions. Stale instructions produce descriptions that reflect how your organization used to work.
  • Don't include sensitive information. Instructions are used in AI prompts. Avoid including credentials, internal URLs, or confidential business information.

Example: Putting it together​

Acme Financial Services is a retail lending company. Our data covers loan origination, credit risk, servicing, and collections.

Key domains: Credit Risk (scoring, default models, PD/LGD metrics), Finance (GL, FP&A, revenue), Servicing (payment processing, escrow, loan modifications), and Collections (delinquency, charge-offs, recovery).

Common abbreviations: acct = account, cust = customer, bal = balance, orig = origination, pmt = payment, lgd = loss given default, pd = probability of default, mob = months on book, dlq = delinquent, co = charge-off.

Generate all descriptions in English.

See also​