Principles

​

The Goal of Context Engineering

Context engineering optimizes the performance of your analytics agent. Well-engineered context leads to more accurate, reliable, and cost-effective responses.

​

Core Performance Metrics

The performance of your analytics agent is measured across three key dimensions:

​

Reliability

• Percentage of questions answered - How often the agent can provide a response
• Percentage of correct answers - How accurate those responses are

​

Speed

• Response time - How quickly the agent can process and respond to queries

​

Costs

• Token costs - The computational cost of processing context and generating responses
• Query execution costs - The cost of running SQL queries against your data warehouse

​

Core Principles

Context engineering follows the same principles as data engineering:

​

Measure

Track your agent’s performance across all three metrics:

• Monitor query accuracy and answer rates
• Measure response times
• Track token usage and query execution costs

​

Iterate

Continuously improve your context based on real-world usage:

• Identify patterns in failures and gaps
• Add missing context or clarify ambiguities
• Test improvements with sample queries
• Refine based on user feedback

​

Optimize

Find the optimal balance for your specific use case:

• Too little context: Agent can’t answer questions, writes incorrect queries, or needs multiple exploratory queries (increasing costs)
• Too much context: Higher token costs, slower responses, and confused answers from processing irrelevant information
• Optimal balance: Include all necessary information without exploratory queries, exclude irrelevant schemas, and organize context modularly

​

Concrete Rules

​

1. Be Exhaustive and MECE

Your context needs to be Mutually Exclusive, Collectively Exhaustive (MECE) so that the agent is reliable:

• Collectively Exhaustive: All metrics and data points your users might ask about should be defined in your context
• Mutually Exclusive: Each metric should have only one canonical definition—no conflicting definitions across tables or documentation
• Consistent across tables: The same metric or data point should mean the same thing wherever it appears, ensuring consistency across your schema

Why it matters: Missing metric definitions lead to incomplete or incorrect answers. Conflicting definitions across tables cause inconsistent responses. The agent needs a single source of truth for each metric.

​

2. Balance Token Costs

But not too exhaustive so that it’s not too costly in terms of tokens:

• Include only relevant schemas, tables, and documentation
• Avoid redundant or unnecessary information
• Focus on what your users actually need

Why it matters: Every token costs money. Including irrelevant context increases costs without improving quality.

​

3. Minimize Query Execution

Provide enough context upfront so that it’s not too costly in terms of query execution:

• Provide enough context upfront so the agent doesn’t need to explore the schema through multiple queries
• Document relationships and join patterns explicitly
• Include example queries that demonstrate efficient patterns

Why it matters: Each exploratory query costs money and time. Well-documented context reduces the need for trial-and-error queries.

​

4. Keep It Modular

Your context should be modular so that it’s not too costly in tokens and keeps the agent focused:

• Organize context into logical, domain-based modules
• Structure documentation and rules hierarchically
• Enable the agent to load only relevant pieces of context at a time

Why it matters: Modular context allows the agent to read small, focused pieces of information rather than processing everything at once. This reduces token costs and improves focus.

​

Next Steps

Context Playbook

Apply these principles step-by-step with our context engineering playbook.

Context Configuration

Learn how to configure and structure your context effectively.