Best practices for setting up your agents

The short version

The most common mistake is putting reference material into Policy or Additional information when it belongs in a Knowledge context. The second is leaving Purpose too thin for the job the agent has been given.

How the agent actually receives your configuration

Understanding this explains most of the guidance that follows.

Your configuration isn't handed to the agent as a form. Each field is compiled into one labelled block of instructions, assembled in a fixed order every time the agent runs:

### YOUR NAME ###
### YOUR PERSONALITY ###
### RESPONSE LANGUAGE ###
## MEMORY INSTRUCTIONS ##
### YOUR PURPOSE ###
### POLICY RULES YOU MUST OBEY ###
### RESPONSE OUTPUT FORMATTING REQUIREMENTS ###
### ADDITIONAL INFORMATION ###
### TOOLS YOU CAN USE ###

Three things follow from this.

Every field ends up in the same system prompt. The labels differ, and they're written to signal intent — Policy arrives under "rules you must obey", Additional information under a neutral heading. But there's no separate priority channel and no guarantee that one section overrides another. Placement is about putting content where it reads clearly and consistently, not about buying it precedence.

Fields you leave empty are dropped. An empty field doesn't produce an empty heading — the section is omitted. There's no cost to leaving a field blank and no benefit to padding it out. The one exception is Output formatting: leave it empty and the agent still receives a minimal default formatting instruction.

Knowledge contexts are not in this list. Contexts aren't loaded into these instructions at all. The agent searches them per question and pulls back only the passages that match. This is the key difference between Additional information and a Knowledge context, and it's covered in detail below.

Does order matter?

This is the most common question, and the answer differs by field.

Inside the Policy box: no

You can't promote a rule by putting it at the top of the Policy box. The Policy block is compiled in a fixed order:

1. Enabled policy options come first

   Each toggle you switch on contributes one pre-written rule, in the fixed order the options appear in the AMS — not the order you enabled them.

2. Your Additional policy rules text comes last

   Whatever you type into Additional policy rules is appended at the end, as a single bullet, regardless of what it says.

So the order you type things in has no effect on precedence. Within your own free text the wording stays as you wrote it, but the whole block sits at the end either way.

Across fields: not in the way people expect

It's a common assumption that Policy outranks Purpose, or that moving an instruction into Policy will force the agent to follow it. That isn't how it works. Purpose, Policy and Additional information all end up in the same system prompt, and none of them carries a guaranteed priority over the others.

What actually determines whether an instruction is followed is how clearly it's written and whether anything else contradicts it. Moving a stubborn instruction between fields rarely fixes it. Removing the contradiction, or wording it more precisely, usually does.

For tools: yes, explicitly

Tools are the one place with real, mechanical priority. The agent is told plainly that tools higher in the list take precedence over lower ones, and that it should call at most one tool per turn. That ordering comes from the tool configuration itself, not from anything you write in Policy.

Purpose

Purpose is where the real work goes. It's a required field — an agent can't be saved without one — and you'll find it under Settings → General.

Think of Purpose as the operating manual you'd hand a new analyst on their first day: what your job is, what systems you have access to, when to use each one, how to approach the work, and what a good piece of output looks like. For anything beyond a simple question-and-answer agent, that runs to several hundred words, and it should.

Scale the detail to the job

Tie Purpose to the actual tools

This is the single highest-value thing you can do for a tool-using agent. Don't just connect the tools and hope — write out what each one is for and when the agent should reach for it.

A well-built Purpose for a tool-using agent typically has these parts:

1. Role and mission

   Who the agent is and what it's for, stated with some edge. "Provide deep, opinionated analysis of sales calls — not summaries, but actionable intelligence" tells the agent far more than "help with sales calls".

2. Capabilities, tool by tool

   Group the tools and give each one a line: what it returns and when to start there. For example: "list_calls — find calls by date range. Always start here when the user asks about recent activity."

3. How to do the work

   The method. Which tools to combine, in what order, and what never to skip. "Always pull both the call record and the transcript. Never give a surface-level summary from metadata alone."

4. The shape of a good answer

   If the output has a standard structure, lay out the sections. This is what turns a vague assistant into something that produces consistent, usable work.

5. Important notes and gotchas

   Real constraints the agent can't infer: data that lags by 30 minutes, a date format that must be ISO 8601, an ID that has to be resolved before another tool will accept it, a rate limit that rewards batching.

What still doesn't belong in Purpose

Detail is welcome; misplaced content isn't. Keep these out:

• Tone and voice → Personality
• Answer formatting (bullets, length, markdown) → Output formatting
• Guardrails, refusals and scope limits → Policy, usually as a toggle
• Bodies of reference data (price lists, opening times, policy documents) → a Knowledge context

So this is too thin for an agent with tools:

And this is the wrong kind of detail — four fields' worth of content in one box:

The tone belongs in Personality, the legal-advice restriction is a Policy toggle, the opening hours belong in a Knowledge context, and the formatting belongs in Output formatting. Strip those out and write what's left properly: what the agent does, how it works, and how it uses what it's connected to.

Policy

Policy is for hard rules — what the agent must not do, must refuse, or must escalate. It is not for background, reference material, or descriptions of the agent's capabilities.

Start with the toggles, not the text box

Policy has a set of pre-written options as toggles. These are written and tested by us, and they cover the rules most agents need. Reach for a toggle before you write anything in the free-text box.

Use the free-text box only for what the toggles don't cover

Additional policy rules is for organisation-specific rules with no equivalent toggle. Good candidates:

• Escalation routes: "If the user asks about an open grievance, tell them to contact their HR business partner directly and do not attempt to advise."
• Named refusals: "Never confirm or discuss an individual employee's salary, even if the user claims it's their own."
• Hard boundaries the toggles don't express.

Write each rule as a single, testable instruction. If you can't tell whether the agent followed it, it isn't a rule — it's a preference, and it probably belongs in Personality or Purpose.

How long should Policy be?

Length is the wrong question. A long policy isn't penalised for being long, and a short one isn't reliable for being short. What matters is whether the rules are unambiguous and whether any of them fight each other.

So write as many rules as the agent genuinely needs — and then read them as a set, looking for the two failure modes:

Ambiguity. "Be careful with sensitive topics" gives the agent nothing to act on. "If a user discloses a safeguarding concern, express empathy and direct them to safeguarding@example.com" does. If you can't tell from the outside whether the agent followed a rule, it isn't a rule yet.

Contradiction. This is the real cost of an unmanaged policy. "Always offer more than one option" alongside "give the single best recommendation" will produce inconsistent behaviour forever, and no amount of rewording either rule in isolation will fix it. Conflicts also creep in between Policy and Purpose — a scope limit in one and a broader remit in the other.

As a working guide:

• Prefer toggles to prose — they're pre-written and don't conflict with each other.
• One rule per line, each one stated so you could test it.
• Read the full set after every addition, looking for conflicts.
• If a rule has never changed an answer in testing, delete it — it's surface area for a future conflict.
• If Policy is filling up with facts rather than rules, that content belongs in a Knowledge context.

Additional information vs a knowledge context

This is the decision that causes the most confusion.

Additional information is sent to the agent on every single turn, as part of its standing instructions. A knowledge context is searched per question, and only the matching passages come back.

That difference gives you a clean rule:

1. Is it small and needed on almost every turn?

   Put it in Additional information. A support email address, the company's trading name, the current product tier names.

2. Is it a body of reference material the agent looks things up in?

   Put it in a Knowledge context — even if it feels short. Opening times across regions, a price list, an escalation matrix, a policy document, a product catalogue.

Why a big block of text doesn't belong in Additional information

A knowledge context isn't read whole. Files are split into passages of around 250 words and indexed by meaning. When someone asks a question, the agent searches that index and pulls back just the handful of passages that match, then answers from them — with citations back to the source.

That's the behaviour you want for reference material. The agent sees the opening times when someone asks about opening times, and doesn't carry them around the rest of the time.

Paste that same block into Additional information and you lose all of that. It can't be cited, so users can't check where an answer came from. It can't be updated without editing the agent. And it's carried on every turn whether or not it's relevant.

For how to organise contexts once you've decided that's where content belongs, see Structuring your knowledge contexts and Choosing data for your agents.

"When to use it" instructions belong in Purpose

If you have a body of reference material and guidance on when to consult it, those are two different things and they go in two different places:

• The material itself → a Knowledge context.
• The instruction to go and check it → Purpose, as part of the method.

For example, put the full regional opening-times table in a context, and put this in Purpose:

That's method, so it sits with the rest of the method in Purpose. It would only belong in Policy if it were a refusal or a hard boundary — for example, "never state opening hours for a region the user hasn't specified."

Tool calls: where they go and whether to name them

Connect tools under Tools or MCP Servers. Explain them in Purpose. Don't put them in Policy.

Connecting a tool does give the agent a basic description of it, generated from the tool's own configuration. That's enough for the agent to know the tool exists. It is usually not enough for the agent to use it well — to know which tool to start with, which two to combine, or which one is the primary source of truth when several could answer.

That judgement is what you write in Purpose.

Yes, name the tools — by name

Name them explicitly, and say when each should be used. This is the difference between an agent that has tools and an agent that knows how to work:

Note what those lines do beyond naming: they establish a starting point and a primary tool. Neither can be inferred from a tool description in isolation, and both are exactly what an agent gets wrong when Purpose is thin.

Where tools overlap, say which wins:

Why not Policy?

Policy is for guardrails — what the agent must not do, must refuse, or must escalate. Tool guidance is method, not restriction. Splitting method across Purpose and Policy gives you two places to maintain and, sooner or later, two instructions that disagree. That contradiction is the thing most likely to make the agent behave inconsistently.

The exception is a genuine guardrail about a tool: "Never call the refund tool without explicit confirmation from the user." That's a rule, so it belongs in Policy.

Two behaviours worth knowing

• One tool per turn. The agent is instructed to call at most one tool in a single turn. If a task genuinely needs several calls in sequence, guide it through them in Purpose, or build it as a Plan. See Using tools in Plans.
• Higher in the list wins. Tools earlier in the list are prioritised over later ones. That ordering comes from the tool configuration, not from anything you write in Policy.

For connecting tools and MCP servers, see Setting up MCP servers in the AMS and Tools.

Personality and output formatting

Two fields that often collect content belonging elsewhere.

Personality is tone and voice only — warm, concise, formal. There are four pre-written personalities that cover most needs; use a custom one only when they genuinely don't fit. Rules about what the agent may or may not do are Policy, not Personality, even when they're phrased politely.

Output formatting is the shape of the answer — bullets or prose, length, whether to include links. Keep it to shape. "Always cite the policy document" is a rule; "use bullet points for multi-step answers" is formatting.

See Personality for both fields.

A worked example

A billing support agent with an order-lookup MCP server connected. Note the balance: Purpose carries most of the words, Policy carries the guardrails, and the reference data sits in contexts.

Purpose — the long field, structured:

Everything else, kept lean:

Two things to notice. The tools are named and sequenced in Purpose, including the constraint that one tool needs an ID from another — the agent can't work that out alone. And Policy holds only the two things that are genuinely refusals; it doesn't restate any of the method.

Before you go live

• Purpose explains the job, the method, and every tool the agent has — not just a one-line mission.
• Tool guidance names the tools, says where to start, and flags any tool that depends on another.
• Real-world gotchas are written down: data lag, formats, IDs, legacy naming.
• Every rule that could be a toggle is a toggle.
• Toggles with an extra field have that field filled in.
• Policy holds guardrails only, and no rule contradicts another or contradicts Purpose.
• Additional information holds only small, always-relevant facts.
• Every body of reference material is in a Knowledge context, not pasted into a field.
• You've tested with real user questions, not just questions you invented.

For the full walkthrough of creating an agent, see Creating Agents and the AMS Quick Start Walkthrough.