# Writing the brief

The brief is the agent's job description. It composes into the system prompt, so this is the file that matters.

Source: https://docs.omazy.ai/agent/brief/

The brief is where you say who the agent is and what it may do. It composes and
publishes into the system prompt, which means two things worth remembering:

1. Edit the brief, never the prompt. The next publish overwrites the prompt.
2. Nothing you write here is live until you publish.

## What a good brief contains

**Identity.** One or two sentences. Who does this agent answer for, and in what
tone. Resist the temptation to write a personality essay. The model is already
good at sounding human, and every extra adjective competes for attention with
your actual rules.

**Scope.** What it may answer, and what it must not. Be concrete. "Do not give
medical advice" is a rule. "Be careful with sensitive topics" is a mood.

**Handover rules.** The single highest-value section, and the most commonly
vague. Name the situations:

> Hand over to a human for refunds, complaints, anything about an existing
> order, and any question about a price that is not in the catalog.

"Hand over when unsure" fails because a model is rarely unsure. That is the
whole difficulty.

**Format.** Chat is not email. Ask for short answers, and say so explicitly.

## What to leave out

Facts. The brief is instructions, not knowledge. Prices, hours and policies
belong in knowledge or the catalog, where you can change them without
republishing the agent and where the answer can cite a source.

A brief that contains your opening hours will be wrong in six months, confidently
and in the agent's own voice.

## Test the brief, not the prose

A brief reads well and still behaves badly. The only check that counts is
running your real questions through Testing and seeing what comes out.

Change one thing at a time. If you rewrite the identity, the scope and the
handover rules together and the agent gets worse, you have learned nothing
except that it got worse.