Task Instructions

Task Instructions tell the Hands (task executors) how to perform their work—SQL syntax rules, query patterns, search strategies, and execution guidelines.

Overview

Task Instructions bypass the Head (agent brain) and go directly to the specific task executor that needs them. The Head never sees these instructions—they're meant for the Hands only.

circle-exclamation

When to Use Task Instructions

Use Task Instructions when you need to:

  • Define SQL generation standards and patterns

  • Set query performance guidelines

  • Specify how to handle edge cases in query generation

  • Enforce data access rules at the SQL level

  • Configure search behavior or ranking criteria

  • Set formatting rules for generated queries

Fields

Field
Required
Description

type

Required

Must be task-instructions

domain

Required

Which domain(s) this applies to: "*", "marketing", etc.

tasks

Required

Which task(s) this targets: "*", "text-to-sql", etc.

entity

Optional

Limit to specific entity: "customer", etc.

Available Tasks

Task Name
Purpose

text-to-sql

Converts natural language questions to SQL queries

semantic-search

Searches documentation and knowledge bases

data-story

Generates insights and narrative explanations

*

Applies to all tasks (use sparingly)

Text-to-SQL Instructions

The most common use case for Task Instructions is guiding SQL query generation.

Example: Global SQL Standards

Example: Domain-Specific SQL Rules

Data Story Instructions

Guide how the agent explains insights and generates narratives.

Example: Storytelling Guidelines

Campaign Performance: Up 23%

Your email campaigns drove 847 conversions last month—23% higher than November and 45% above the same period last year.

What's driving growth:

  • Enterprise segment: +67% (new account-based campaigns)

  • Product category A: +34% (seasonal promotions)

  • Organic search: +12% (SEO improvements)

What to watch:

  • Mobile conversion rate declined 8% (mobile UX review recommended)

  • Weekend campaigns underperforming weekday by 15%

Next steps:

  • Double down on enterprise ABM campaigns

  • Test mobile checkout improvements

  • Shift weekend budget to weekdays

Real-World Examples

Example 1: E-commerce SQL Standards

Customer Lifetime Value

Use the pre-calculated customer_ltv field from analytics.customer_metrics. Do NOT calculate LTV in ad-hoc queries—it requires complex cohort logic.

Monthly Active Users (MAU)

Stickiness (DAU/MAU)

Data Freshness

Check data freshness before running queries:

If data is >24 hours old, warn the user before returning results.

Bad:

Provide Query Templates

Instead of describing what to do, show working SQL examples:

Task Instructions vs Knowledge

Not sure which to use? Here's the distinction:

Task Instructions
Knowledge

Goes directly to task executor

Seen by both Head and Hands

SQL syntax, query patterns

Business definitions, context

"How to execute"

"What things mean"

Technical implementation

Business logic

Example:

Knowledge:

Task Instructions:

Last updated