> For the complete documentation index, see [llms.txt](https://doc.aissist.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.aissist.io/tutorial/tune-aissist-behavior/how-to-write-better-ai-instructions.md).

# How to Write Better AI Instructions

*Last updated: May 29, 2026*

Good instructions make Aissist more accurate and more consistent.

Weak instructions lead to vague replies, missed steps, and unnecessary escalation.

Use this guide to write instructions that are clear, bounded, and easy to follow.

### Write clearer instructions

#### Start with one clear objective

State the job in direct language.

Weak instruction:

> Answer customer questions about pricing.

Stronger instruction:

> Provide concise pricing guidance. Do not give exact pricing without required inputs. Escalate when pricing depends on unavailable data.

This works because it defines:

* the task
* the limit
* the escalation trigger

#### Define what Aissist should not do

Aissist tries to be helpful. If limits are unclear, it may fill gaps.

Add explicit rules such as:

* do not guess
* do not estimate unavailable values
* do not invent product rules
* escalate when unsure

This is especially important for pricing, policy exceptions, and technical troubleshooting.

#### Separate facts from instructions

Put facts where they belong.

Use:

* **Workspace Context** for shared business facts
* **Assets** for reference knowledge
* **Instructions** for behavior rules
* **Sub agents** for workflow-specific logic

For example, do not explain a return policy only in instructions if the policy belongs in an asset.

See [Tune Aissist Behavior](/tutorial/tune-aissist-behavior.md) for how these layers work together.

#### Prefer intent over exact phrasing

Do not force one fixed sentence unless the wording must stay exact.

Weak instruction:

> Respond with: "You can order just one item."

Stronger instruction:

> Confirm that the customer can order a single item. Use natural wording that matches the conversation.

This keeps replies flexible without losing the intended message.

Use exact wording only when it is required for:

* legal or compliance statements
* approved disclaimers or promises
* text that must match another workflow exactly

For conversation closings, define the outcome instead of scripting the full reply.

<details>

<summary>Example: close a resolved support conversation</summary>

Weak instruction:

> When the user confirms the issue is fully resolved, respond with: "I'm glad we were able to resolve your issue. It was a pleasure assisting you today! If you need any further help, feel free to reach out anytime—we're available 24/7. Have a wonderful day!"

Stronger instruction:

> If the user confirms the issue is fully resolved, politely close the conversation.
>
> * Thank the user for contacting support.
> * Mention that help is available 24/7 if needed.
> * Wish the user a great day.
> * Do not continue troubleshooting or ask additional questions after the user confirms resolution.

This works better because it:

* preserves the goal
* lets the wording fit the conversation
* avoids repetitive scripted replies

</details>

#### Keep instructions bounded

Avoid open-ended phrasing such as:

* if relevant
* explain thoroughly
* add more details

Use precise constraints instead:

* keep the reply under 3 sentences
* ask one question at a time
* do not expand beyond the defined explanation

Specific constraints make replies more stable.

### Build workflow instructions

#### Use step-based workflows

Aissist follows step-by-step logic better than long paragraphs.

Instead of:

> When customers ask about pricing, answer clearly and collect details before escalating.

Write:

#### Pricing request flow

1. Ask for quantity.
2. Ask for ZIP code.
3. Collect any other required input.
4. Escalate if exact pricing still depends on unavailable data.

This reduces ambiguity and keeps behavior consistent.

#### Start sub agent instructions with a workflow title

For sub agents, begin with a short workflow name.

Then list the steps for that workflow.

This makes the instruction easier to scan and easier to maintain.

Instead of:

> When users ask where their order is, check whether they shared the order number, ask for it if missing, provide tracking details if available, and escalate if tracking cannot be found.

Write:

#### Order tracking workflow

1. Check whether the user shared the order number.
2. Ask for the order number if it is missing.
3. Provide tracking details if they are available.
4. Escalate if tracking is unavailable or the issue needs human review.

This structure works well for returns, cancellations, billing, and other workflow-specific sub agents.

#### Keep troubleshooting sequential

Give one next action at a time.

Do not send several troubleshooting steps in one message.

Use this pattern:

1. diagnose from the current message
2. give one clear next step
3. wait for the result
4. continue only if needed
5. escalate after the defined limit

This keeps the conversation grounded in the current state.

#### Define escalation clearly

Do not write vague rules like:

> Escalate if necessary.

Write exact triggers instead:

* required data is missing
* the user asks for a human
* the answer depends on unavailable system access
* the workflow remains unresolved after a defined number of steps

Use **Escalation** in workspace settings to customize global handoff rules.

Use sub agents when only one workflow needs special escalation behavior.

See [Configure Workspace Settings](/tutorial/tune-aissist-behavior/configure-workspace-settings.md) for workspace fields.

See [Streamline with Human Team](/tutorial/streamline-with-human-team.md) for handoff workflow guidance.

### Format for readability

#### Prefer lists over tables

Use bullet lists and short sections for most instructions.

This structure is usually easier to follow than tables.

Use lists for:

* rules
* step-by-step workflows
* conditions and exceptions

Use tables only when the relationship between rows and columns matters.

For example, tables can work for:

* comparing instruction levels
* mapping channels to behaviors
* listing fixed field requirements

If a table is not necessary, rewrite it as headings and bullets.

<details>

<summary>Example: rewrite a table as a workflow list</summary>

Less effective:

| Situation              | Response                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------ |
| User asks for a refund | Ask for the order number, ask for the reason, explain the policy, escalate if needed |
| User asks for tracking | Ask for the order number, provide tracking if available, escalate if unavailable     |

Better:

#### Refund request

* Ask for the order number.
* Ask for the reason for the refund.
* Explain the relevant policy.
* Escalate if the case needs review.

#### Tracking request

* Ask for the order number.
* Share tracking details if available.
* Escalate if tracking is unavailable.

The second version is easier to scan, update, and follow.

</details>

### Put each rule in the right place

Use the field that matches the job:

* **Instruction** — universal behavior rules
* **Context** — shared business facts
* **Tasks** — what the workspace should accomplish
* **Escalation** — global handoff logic
* **Sub agent Scenario** — when a workflow should trigger
* **Sub agent Instruction** - how the workflow should work
* **Sub agent Task** — what that workflow should achieve
* **Sub agent Summary** — structured notes for the human team
* **Assets** — reference knowledge retrieved only when relevant

If one rule applies only to returns, billing, or tracking, move it into a sub agent.

### Common mistakes

Avoid these patterns:

* mixing facts, tone, and workflow steps in one long paragraph
* leaving unknowns undefined
* forcing rigid wording for every reply
* turning example replies into required scripts
* using instructions where an asset or action is needed
* writing escalation rules without clear triggers

### Best practice

Keep instructions short.

State limits directly.

Use sub agents for workflow logic and assets for knowledge.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.aissist.io/tutorial/tune-aissist-behavior/how-to-write-better-ai-instructions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.