> Source: https://builder-docs.ema.ai/builder-guides/chat/writing-instructions
> Title: Writing Effective Instructions

# Writing Effective Instructions

> These principles help you create clear, concise, and effective instructions for Ema's AI Employees across different use cases. Following them ensures better accuracy, faster outcomes, and less back-and-forth when building workflows.

## Core Principles for All Agents

### Clarity and Specificity

Be exact about what you want.

-   Instead of: _Search sales_
-   Say: _Search sales reports for Q1 2023 in PDF format._

### Include Relevant Context

Tell the AI Employee why or where to look.

-   Example: _Retrieve recent competitive analysis from Gartner published in the last six months._

### Be Concise but Complete

Aim for short, direct instructions that still give enough detail.

-   Instead of: _Go through these and see if there's anything interesting_
-   Say: _Summarize the main findings from these documents._

### Structure Your Request

Organize multi-part instructions with bullet points.

-   Example:
    -   Search for competitor analysis
    -   Search for market trends
    -   Search for customer feedback

### Define the Desired Output

Tell the AI Employee exactly what format and length you expect.

-   Example: _Generate a one-page summary of key market insights._

### Specify Feedback and Iteration Points

Let the AI Employee know if you want interim results before final output.

-   Example: _Present initial search results before proceeding to detailed analysis._

## Agent-Specific Principles

### File Search

-   Specify the file type or content type: _Find references to sustainability initiatives in 2022 annual reports._
-   Use metadata filters: _Retrieve only Excel files uploaded after January 2023._

### Web Search

-   Indicate if recency matters: _Find the latest product reviews published within the last month._
-   Specify sources if needed: _Search only Forbes and TechCrunch articles._

### Market Research

-   Define audience or market: _Analyze recent trends in the North American fitness market._
-   Specify insight focus: _Identify emerging competitors and consumer behavior shifts._

### Structured App Search

-   Be clear about filters: _List open tickets from ServiceNow for priority 1 issues from the past week._
-   Define output fields: _Provide only ticket ID, summary, and status._

### Intent Classifier and Text Categorizer

-   State categories upfront: _Classify chat messages into complaint, request, or feedback._
-   Explain how to handle ambiguities: _If unclear, label as "other" and flag for manual review._

### Rule Validation

-   State rules precisely: _Flag transactions above $10,000 without documented approval._
-   Provide exceptions: _Allow deviations if marked as Executive Override._

### Chart Builder

-   Define the dataset and comparison: _Plot monthly sales figures comparing product A and product B from January to June._
-   Specify chart type: _Create a pie chart showing market share percentages by competitor._

### Document Categorizer

-   Define categories and give examples: _Categorize documents as financial report, technical manual, or marketing brochure._
-   Clarify differences: _Financial reports contain quarterly or annual financial data._

### Generate Document

-   Specify language and variant: _Translate document from English to Spanish (Latin America)._
-   Indicate tone and style: _Maintain formal business language suitable for executives._

By applying these principles, you will create instructions that help Ema's AI Employees deliver accurate, efficient, and on-brand results every time.