Custom instructions for conversational AI
Custom instructions are text rules that admins write to shape how conversational AI answers questions across your organization. They teach conversational AI your vocabulary, state which asset types to prefer or exclude, and set the language responses come back in.
Instructions are applied to every conversation, for every user in your tenant. Written well, they make answers noticeably more relevant. Written badly, they degrade answers for everyone—so understanding their limits matters as much as knowing what to write.
To configure custom instructions, see Customize conversational AI.
How custom instructions work
Your instructions are supplied to conversational AI alongside each user's question, then weighed against your catalog's metadata, lineage, and glossary context when it plans an answer. You can see this in a response's reasoning, which refers to your instructions directly when they influenced the result.
Three properties follow from this, and they explain most surprises:
- Instructions are organization-wide. They apply to every user and every conversation. There's no per-persona, per-user, or per-conversation override.
- Instructions express preference, not permission. They shape what conversational AI prefers, excludes, and how it phrases answers. They don't grant or restrict access—each user still sees only what their existing permissions permit.
- Instructions can't reach metadata you don't have. An instruction that filters on an attribute your assets don't carry is quietly skipped. If you write "don't show unpublished datasources" but nothing in your catalog records published status, conversational AI has nothing to filter on.
What to include
The instructions that earn their place are short, concrete, and specific to your organization. These patterns work well:
| Pattern | Example instruction |
|---|---|
| Vocabulary mapping: teach conversational AI what your business words mean in catalog terms | A business layer means a Tableau datasource. |
| Asset type preferences: steer toward the asset types your users want | Do not show Tableau worksheets.Do not return glossaries or categories, only terms. |
| Ranking preferences: state what counts as the better answer | Prioritize certified assets and output ports. |
| Response language: set the language answers come back in | Always respond in Brazilian Portuguese. |
| Organizational context: give conversational AI grounding it can't infer | Finance reporting runs on a fiscal year starting in April. |
A complete set usually runs to five or ten lines:
A business layer means a Tableau datasource.
Do not show Tableau worksheets.
Do not return glossaries or categories, only terms.
Prioritize certified assets and output ports.
Search asset names for all keywords in the question.
Write each rule as a single, testable statement. If you can't tell whether a rule fired by looking at an answer, it's probably too vague to be worth including.
What to avoid
Some instructions actively make conversational AI worse. These are the failure modes seen most often.
Don't write routing or orchestration logic. Instructions that tell conversational AI to classify a question and hand it off to a named skill—without answering it—are the most damaging pattern. Conversational AI selects skills itself as part of answering; there's no separate handoff step for your instructions to drive. Instructions written this way produce replies that announce a skill and then stop, without ever searching your catalog. Let conversational AI choose the skill, and put skill-specific behavior in that skill's own description and instructions instead.
Don't restate access control. Permissions and personas already govern what each user can see. Instructions that duplicate those rules add prompt length without changing what's returned.
Don't filter on attributes you don't populate. Check that the metadata exists before writing a rule that depends on it. See How custom instructions work.
Don't let the list grow unchecked. Every instruction is applied to every question. Long, layered, or contradictory rule sets pull conversational AI away from the user's actual question. Prune rules that are no longer needed rather than accumulating them.
Don't encode one team's preferences organization-wide. Because instructions are tenant-wide, a rule that suits one domain applies to everyone. If a preference only makes sense for one team or use case, it belongs in a skill rather than in custom instructions.
Custom instructions vs. other controls
Custom instructions are one of four controls, and they solve different problems:
| Control | Scope | Set by | Use it for |
|---|---|---|---|
| Custom instructions | Every conversation in tenant | Admin | Organization-wide vocabulary, preferences, and response language |
| Skills | Questions that match skill | Admin or contributor | Repeatable, task-specific behavior with its own method and output format |
| Memory | One user's conversations | Learned automatically | Personal context, corrections, and stated preferences |
| Personas | Assets user can access | Admin | Access control, which conversational AI respects |
If a behavior is needed for a specific kind of question rather than for all of them, prefer a skill over a custom instruction.