I have written my own best practice guide for writing instructions for data agents. This is because I have struggled to find comprehensive documentation. The sources for the assertions in my guide are:
- Google documentation (scant)
- Webinars
- Chats with Gemini
- Trial-and-error testing
I’ve attached my findings so far. Has anyone got anything to add to this? Or anything they would call out as incorrect? It would be great to share what works for others, as we are right at the start of our conversational analytics journey.
Data Agent Instructions Style Guide
About
Agent instructions are the primary tool for personalising how a data agent behaves.
Instructions allow Developers to add broader context, beyond the field-specific context that is provided by LookML. They bridge the semantic gap that LookML doesn’t cover:
| ⚙️ LookML | 📖 Instructions | |
| Scope | Field-specific context | Domain-specific context |
| Content | Defines how fields are calculated and referred to in the real world | Defines organisational preferences, operational nuances, guardrails and formatting rules. |
| Purpose | Helps the LLM to accurately map the terms used in a user’s prompt to exact fields. | Helps the LLM to provide responses that are contextually relevant, and aligned with the user’s expectations. |
Instructions are applied on an agent-by-agent basis. It is currently not possible to share instructions across multiple data agents.
Format & style
Sentences should be concise, but grammatically correct. Too much information can cause the LLM’s attention to drift.
- Use short sentences: write short, sharp sentences. Break up long sentences that contain multiple clauses, commas, or "and"s.
- Use LookML syntax: always refer to fields using their fully-qualified LookML name, and refer to filter operators using LookML expressions (e.g.
Filter \`products.publish_date\` to "7 days"). - Avoid Filler: keep text direct. Avoid excess detail and conversational filler.
Instructions are entered into a free-form, plain-text box that does not support formatting or markdown. To make the instructions more readable to humans, and help the LLM to recognise where one task ends and the next begins, use punctuation to mark logical boundaries and prevent rules from bleeding together:
| Formatting Element | When to use | How it helps the LLM |
|
Hashtags (#) |
Use for section headings (e.g. # GUARDRAILS & CONSTRAINTS) |
Indicates that the text is a high-level category that governs all the bullet points beneath it (# is a Markdown header). |
|
Capitalisation |
Use for:
|
Acts as a “loud hailer” that captures the LLM’s attention. It helps distinguish important text from standard sentences. For rules, the aggressive framing signals that the rule is non-negotiable. For LookML commands, capitalisation isolates code from the rest of the sentence. |
|
Empty Line Breaks |
Use to insert a divider between sections. |
Signals that the previous context block has ended, and a new one has opened. |
|
Bullet points (-) |
Use hyphens (-) to create pseudo bullet points for each instruction. |
LLMs treat a solid block of text as a single entity. This can lead to attention drift, where the information in the middle gets lost. Bullet points “atomise” the text into discrete instructions that can be processed separately. |
|
Nested bullet points ( -) |
Use hyphens (-) prefixed by 4 character spaces to create nested bullet points. |
Indicates the indented text is in a hierarchical relationship with the text above. |
|
Numbered lists |
Use numbered lists (1., 2., 3.) when the order of operations matters e.g. for outlining sequential steps. |
LLMs are highly receptive to chronological prompting. If you only use bullet points for a multi-step process, then the LLM may attempt step 3 before step 1. |
|
Backticks (\`) |
Use to enclose LookML field names e.g. |
Isolates code from the rest of the sentence. |
|
Straight Double quotes (") |
Use to enclose:
|
Isolates user inputs / code from the rest of the sentence. |
|
Straight Single quotes (') |
Use to enclose filter strings in the golden queries section e.g. |
Isolates filter strings from the rest of the query. |
|
Square brackets (\[ \]) |
Use to tag the type of analysis performed by a golden query e.g. |
Isolates classification labels from instructions. |
Constraint words (ALWAYS and NEVER)
Constraint words are used to enforce critical instructions.
Normal instructions tell an agent what it should do. They are treated as “soft guidelines” that provide helpful context, rather than absolute boundaries. If there are competing instructions between the agent instructions and the user’s prompt, the LLM may decide to drop the agent instructions in order to satisfy the user.
Capitalised constraint words like ALWAYS and NEVER capture the LLM’s attention, giving a heavier weighting to that instruction. LLMs have been trained to treat particular trigger words as hard-coded logic. If you use “always” or “never” in a standard sentence, without capitalisation, it will be read as a strong preference. Capitalisation amplifies the instruction so that it is read as an absolute boundary.
⚠️ Beware of Constraint Collision
You should avoid overusing constraint words. Forcing too many absolute rules onto the LLM creates "constraint collision," where the rules fight each other for priority. This will result in either error codes or erratic behaviour (the LLM will arbitrarily ignore rules in order to satisfy the user’s prompt). Try to limit to 3-5 per agent, and definitely less than 8.
If a rule cannot be broken under any circumstance, use one of these five structures:
| Constraint | Purpose | Example |
|
ALWAYS |
Enforces a permanent rule or filter for every single query. |
|
|
MUST |
Prescribes a specific action or step the agent is required to perform |
|
|
NEVER |
Completely forbids a specific behavior to prevent misinformation or hallucinations. |
|
|
DO NOT EXECUTE |
Acts as a kill-switch that halts query execution if an invalid or unsafe condition is met. |
|
|
STRICTLY |
A high-priority modifier that can be added to the commands above to strip away any remaining edge cases. It acts as an absolute blocker that cannot be overridden, even by creative prompts. |
|
Content
Instructions should include up to 8 sections. Not all of 8 sections may be required - only step in when you need to define a non-standard behaviour.
The exact wording of each section heading does not strictly matter. These are not specific code commands. The literal meaning does matter, as the LLM uses them to categorise and prioritise which rules to focus on at different points in the execution workflow:
- GUARDRAILS: signals strict boundary enforcement at the query level
- BEHAVIOURS: signals conditional actions at the query level
- STYLE: signals low-priority aesthetic choices at the visualisation level
| Section | Purpose | Example |
|
# PERSONA |
Defines the agent’s purpose and conversational tone. It has a natural tendency to be chatty, but this can be overridden. The “factory setting” is a passive data translator. |
- You are a Sales & Strategy Lead. Your mission is to help stakeholders detect sales patterns, understand market shifts and identify emerging trends.
|
|
# GUARDRAILS & CONSTRAINTS |
Outlines strict boundaries, and forbidden behaviors. |
- ALWAYS set the run_looker_query limit to 5000 rows unless otherwise specified.
|
|
NEVER |
Completely forbids a specific behavior to prevent misinformation or hallucinations. |
NEVER calculate a time-based change without displaying the time period it is based on.
|
|
# EXPLORE SELECTION RULES |
Directs the agent to specific Explores based on the subject matter of the user's prompt. (Only use when the agent connect to more than one Explore.) |
- Primary Sales & Revenue: use the `orders` Explore for any queries regarding sales, revenue, products purchased, order volumes, or financial metrics.
|
|
# BUSINESS TERMS |
Defines how the agent should interpret common terms that cannot be captured on the LookML layer e.g. how to handle requests for "recent orders" or "at-risk customers". |
- Top/popular: defined by the highest `orders.sold_count`.
|
|
# DEFAULT BEHAVIOURS |
Specifies which filters, timeframes and dimensions the agent should include when the prompt lacks specific details. |
- Unless a specific date range is requested, ALWAYS filter `orders.order_end_date` to "30 days".
|
|
# RELATED FIELDS |
Maps a single term to a set of fields that should be returned together to answer the question (e.g. “city” always returns city, state, and country). |
- If a user requests "by user", create a table and include `users.user_id`,`users.user_name` and `users.country`.
|
|
# FORMATTING & OUTPUT STYLE |
Dictates how the final response should be structured, including visualization rules and textual summaries. |
- Automatically generate a Line Chart whenever a type: time dimension is used, provided there are at least 3 data points.
|
|
# GOLDEN QUERIES |
Provides pairs of natural language questions and the corresponding query that should be executed. Each Explore should have 5-10 of these “perfect pairs” to cover common questions and complex logic like period-over-period analysis. |
(see section on golden queries) |
Length
Instructions should be 500 - 1,500 words long.
The LLM must break down and process the entire instruction set every time a user enters a prompt. LLMs heavily prioritise instructions at the very top and very bottom of a file. When instructions are very long, the instructions that are buried in the middle tend to be forgotten.
Bloated agent instructions directly cause:
- 🐌 Slower Response Times: adds a noticeable 2–5 second lag per prompt.
- 💰 Increased Costs: we are billed for token consumption (i.e. the number of words / pieces of words that are broken down by the LLM).
- 🌀 Erratic Behavior: the agent may arbitrarily ignore some instructions.
Best practices:
- Fix, don't pre-empt: only write an instruction to enforce an essential business boundary, or to correct an undesired behavior observed during testing.
- Avoid redundancy: do not duplicate information that belongs in LookML, like field descriptions or synonyms.
- Trust the foundation: avoid explaining concepts that the agent already understands or performs out-of-the box. For example, you do not need to ask the agent to provide a textual summary, as this is always provided by default.
Golden Queries
Each data agent should have 5-10 golden queries defined.
What?
Golden queries are pairs of natural language questions and the corresponding, verified Looker query.
[Period-over-Period Analysis] Week-over-Week (WoW) Revenue Performance
natural_language_questions: ["what is the weekly trend in revenue?", "how does revenue compare this week to the previous week?", "is revenue up or down compared to last week?", "what is wow revenue?", "Show me our week-over-week revenue performance", "Are we beating last week's sales figures?", "What is the revenue growth compared to last week?", "Revenue WoW", "Weekly revenue comparison"]
looker_query: {
model: my_company
explore: orders
fields: [
orders.order_end_week,
orders.content_revenue_usd,
orders.content_revenue_usd_previous_week_change,
orders.content_revenue_usd_previous_week_percentage_change
]
filters:
orders.is_voided: 'No'
orders.order_end_date: 26 week ago for 26 week
sorts: [orders.order_end_week desc]
}
Why?
Golden queries are arguably the most important part of the instruction set. While they ensure that the specific questions are answered flawlessly, their real value is that they help the LLM learn patterns that can be applied to reason through completely different questions. Think of golden queries as “showing” rather than “telling” the LLM what to do. It turns the agent's job from a complex translation task into a simple pattern-matching task.
This is known as “few-shot prompting”:
- Zero-Shot Prompting (No Examples): you give the LLM an instruction and expect it to figure out based solely on its base training.
- One-Shot Prompting (One Example): you give the LLM one example to establish the pattern, and then give it the real task.
- Few-Shot Prompting (Multiple Examples): you give the LLM a small bank of diverse examples to firmly lock in the structural pattern and logic, and then give it a real task.
When you use few-shot prompting, you trigger “in-context learning”. The underlying LLM does not change, but it uses its short-term memory to analyse the examples and apply the same blueprint. In other words, it is like non-permanent training.
When?
Use diverse examples that show the agent how to handle the primary query patterns. Also use for showing how complex calculations like period-over-period calculation should be performed.
- Ranking and Top-N: how to find top / bottom performers, sorted by count.
- Dimension Breakdown: how to slice metrics.
- Trend Analysis: how to group and filter for a specific timeframe.
- Period-over-Period Analysis: how to perform YoY or MoM comparisons.
- Filtering and Segmentation: how to apply complex filter criteria.
To make it quicker for Developers and LLMs to scan the full instruction set, prefix each golden query with a line containing the type of analysis it performs in square brackets, followed by a concise summary. For example:
[Period-over-Period Analysis] Week-over-Week (WoW) Revenue Performance
How?
Golden queries are written using LookML syntax, rather than SQL. To get the LookML for a query, build the query in an Explore and then use the ‘Get LookML’ option to copy the code generated by Looker.
