Agent Workspace Rules

Improve AI responses with business-specific information and guidelines.

Overview

Agent Workspace Rules allows Admins to provide additional context to Hex's AI prompts through a markdown file. This context is used by all AI agents in Hex when generating responses, helping them better understand your business context, data conventions, and preferred practices.

This feature is similar to Claude Projects or Cursor rules - by providing high-level context to your AI agent, you can influence the responses you get and ensure consistency across your team's work.

Since these rules apply to the entire workspace, only workspace Admins can modify the rules.

Configure Agent Workspace Rules

To configure Agent Workspace Rules for your workspace:

1. Navigate to Settings > AI & agents
2. Scroll down to the Context section
3. Click Edit to open the markdown editor
4. Add your business context, guidelines, and preferences
5. Click Save to apply the changes

You can also upload a markdown file directly.

What to include in Agent Workspace Rules

Your Agent Workspace Rules file can include any information that would help Hex's AI better understand your business context and generate more relevant responses. Here are some examples:

Business context

• Company-specific terminology and definitions
• Key metrics and KPIs your team focuses on
• Business processes and workflows
• Industry-specific considerations

Data conventions

• Naming conventions
• Preferred data formats and standards
• Common data transformations and calculations
• Data quality guidelines

Analysis preferences

• Preferred visualization types for different data scenarios
• SQL style guidelines and best practices
• Common analysis patterns and approaches

Example Agent Workspace Rules content

# Data Warehouse Context

## Terminology

- The business is divided into three segments: Small-midsize (SMB), Mid-market (MM), and Enterprise (ENT).
- The key metrics we track are Monthly Recurring Revenue (MRR), Lifetime Value (LTV), and Customer Acquisition Cost (CAC)

## Data Modeling Conventions

- Use snake_case for all table and column names
- Date columns should be named with '_date' suffix
- Currency amounts should be stored as decimals, not integers
- Always include timezone information for timestamp fields

## Analysis Best Practices

- Prefer line charts for time series data
- Use bar charts for categorical comparisons
- Include confidence intervals for statistical analyses
- Always filter out test data (user_id < 1000)
- Add comments for complex logic

Agent Workspace Rules: Best practices

• Other considerations:
  • Jargon - Companies often have terms or phrases that are very specific to them. Try and explain what specific words or phrases mean to give agents the best chance of understanding this terminology.
    • Example: The term “S0” is used to refer to a pipeline opportunity that's in stage 0
  • Synonyms - Companies sometimes use multiple words to describe the same concept. Giving this context to agents can help provide suggestions more consistently when folks describe things with different verbiage.
    • Example: The words “organization” and “workspace” are used interchangeably, but “organization” is how it's represented across all data tables

Agent Workspace Rules teach the AI agent your organization's unique context—the tribal knowledge that distinguishes your data team from others. The agent already knows SQL, Python, and analytics best practices. What it needs from you is your business logic, your data architecture, and your specific ways of working.

Think of rules as onboarding a brilliant new analyst who needs to learn your company's specifics, not how to write code. This context will be passed at the beginning of every agent interaction, so utilize it for "universal truths" about your data and business. Context for specific tables should be added at the table documentation.

The best rules file reads like a knowledgeable colleague's handover notes—specific, practical, and immediately useful.

General Tips

• Keep it concise: Focus on the most important context that will improve AI responses. Including too much context can distract the model.
• Focus on general-purpose rules: Limit the rules file to context you want to be included in every prompt. Documentation related to specific tables or columns should live in your data warehouse, the Hex data browser, or other data documentation source.
• Test and iterate: Try different rules and see how they affect AI responses. Rules should be active instantly, so you can test SQL generation in the notebook or Threads.

High-Impact Rule Categories

1. Business Definitions & Logic

Define what metrics mean at YOUR company. The agent can calculate CAC, but it doesn't know you exclude free trials from the denominator.

Good:

- Active user: Logged in 3+ times in rolling 30 days (not just once)
- Churn: No revenue-generating activity for 60 days
- MRR excludes paused accounts but includes discounted plans

Avoid:

- Calculate averages properly (too generic)
- Use appropriate metrics (too vague)

2. Data Governance

Specify your compliance requirements and data handling policies.

Good:

- EU customer data: Apply GDPR masking to any output
- Financial reports: Include audit_timestamp field
- Never join PII tables with marketing tables without approval flag

Avoid:

- Follow data privacy laws (agent assumes this)
- Be careful with sensitive data (too vague)

3. Data Architecture Guidance

Map your actual data landscape—which tables are trusted and which are deprecated. Tip: If you have endorsed tables inside Hex the agent will automatically prioritize those.

Good:

- Customer truth: analytics.dim_customer_v3 (v2 has sync issues)
- Revenue: finance.recognized_revenue only (not billing.invoices)
- Events: Use events_cleaned, raw_events has 15% bot traffic

Avoid:

- Use the right tables (unhelpful)
- Check data quality (agent does this)

4. Company Standards

Document your specific conventions and requirements that go beyond general best practices.

Good:

- Currency: Always USD, converted at month-end rates
- Cohorts: Define by first_purchase_week starting Sunday
- Charts: Brand colors #0A2540 primary, #00D924 success

Avoid:

- Make nice looking charts (subjective)
- Format numbers properly (agent knows this)

5. Domain Intelligence

Share industry context and competitive intelligence the agent couldn't know. Remember to specify the conditions where this information would be useful.

Good:

- Seasonality: 40% of revenue in Q4, plan capacity accordingly
- Benchmarks: Our 15% monthly growth exceeds industry 8%
- Market context: We compete on speed, not price—emphasize time metrics

Avoid:

- Consider business context (too generic)
- Industry matters (obvious)

Writing Principles

• Be Specific: Replace "appropriate filtering" with "exclude test accounts where is_test=true"
• Show, Don't Tell: Include actual column names, real thresholds, specific examples
• Explain Why When Non-Obvious: "Use ship_date not order_date (rev rec policy changed 2024-01)"
• Front-Load Critical Rules: Data governance and common pitfalls should appear first
• Keep It Scannable: Use bullet points, consistent formatting, clear sections

Complete Example: SaaS Analytics Rules

# AwesomeCo Analytics Workspace Rules

## Critical Data Governance
- PII Handling: Mask email domains in all outputs (show user@****.com)
- EU Data: Filter WHERE consent_status = 'granted' for GDPR compliance
- Financial Access: Only use finance.* tables for board reports
- Test Accounts: Always exclude WHERE is_internal = false AND email NOT LIKE '%@dataco.com'

## Source of Truth Tables
- Customers: warehouse.customers_dim (updates 2am UTC daily)
- Subscriptions: billing.active_subscriptions_v2 (v1 deprecated Nov 2024)
- Usage Events: events.user_actions_cleaned (raw has duplicates)
- Revenue: finance.recognized_revenue (not billing.charges)
- Marketing: marketing.campaigns_attributed (30-day window)

## Business Definitions
- MRR: Sum of monthly_amount WHERE status IN ('active', 'paused')
- Active User: 3+ sessions in rolling 30 days, exclude internal
- Churn Date: First day of month after last payment
- LTV: Revenue until churn / (1 - gross_margin), GM = 0.75
- Qualified Lead: Score > 50 AND company_size > 10

## Calculations & Logic
- Fiscal Year: Feb 1 - Jan 31 (Q1 starts February)
- Cohorts: By signup_week, weeks start Monday
- Attribution: First-touch for acquisition, multi-touch for expansion
- Exchange Rates: Use finance.exchange_rates for month-end conversion
- Growth Rates: Month-over-month using compound formula, not simple

## Required Analysis Patterns
- Time Comparisons: Always show YoY and MoM together
- Segments: Break down by plan_type (Starter/Pro/Enterprise)
- Statistical Significance: Min 100 samples for A/B tests
- Forecasting: Use 13-week rolling average for baseline
- Anomaly Detection: Flag if metric deviates >2 std from 30-day mean

## Data Quality Warnings
- orders table: 2% duplicate rows, use orders_deduped
- user_attributes: NULL company_size for 30% of records pre-2024
- revenue_forecast: Only reliable 30 days out
- marketing_spend: Delayed by 3 days, note in analyses

## Stakeholder Preferences
- Executive Reports: Focus on trends not absolute numbers
- Sales Team: Include pipeline_stage breakdown
- Product Team: Segment by feature_flag exposure
- Finance: Show both GAAP and billing revenue

## Industry Context
- Benchmarks: Target 125% NDR (industry avg: 110%)
- Seasonality: Q4 -20% new sales, Q1 +35% (budget cycles)
- Competition: We're 2x pricing of alternatives, emphasize ROI
- Market Position: #3 by revenue, #1 by NPS in our segment

Anti-Patterns to Avoid

Don't State the Obvious

• ❌ "Write efficient SQL"
• ❌ "Handle errors properly"
• ❌ "Consider performance"

Don't Overspecify Technical Details

• ❌ Full function implementations
• ❌ Detailed algorithm specifications
• ❌ Complex regex patterns (unless critical)

Don't Contradict Core Behaviors

• ❌ Rules about response formatting
• ❌ General coding standards
• ❌ Tool usage instructions

Don't Include Secrets

• ❌ API keys or passwords
• ❌ Individual customer names
• ❌ Confidential financial targets

Testing Your Rules

1. Specificity Test: Can a new analyst follow this rule without asking clarifying questions?
2. Value Test: Does this rule contain information unique to our organization?
3. Usage Test: Run typical queries and verify the agent follows your rules
4. Maintenance Test: Flag rules that reference specific dates, versions, or temporary conditions for regular review