> For the complete documentation index, see [llms.txt](https://docs.zbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zbrain.ai/zbrain-documentation/zbrain-zsearch/projects-in-zsearch/editing-search-instructions-in-zsearch.md).

# Editing search instructions in ZSearch

#### What are search instructions? <a href="#what-are-search-instructions" id="what-are-search-instructions"></a>

Search instructions define how the AI operates within a project in ZSearch. They provide guidance on how to interpret queries and generate responses, using the project’s files as context.

Instructions in ZSearch are project-specific and apply only within the project in which they are defined. They are used for all AI interactions in that project and do not affect searches or projects outside it.

Search instructions can be used to specify:

* The role or behavior the AI should follow
* How responses should be structured or presented
* Whether answers must be strictly grounded in project files
* Any constraints on tone, style, or scope

By configuring search instructions, teams ensure that AI-generated responses remain consistent, relevant, and aligned with the purpose of the project.

#### Accessing the instructions panel <a href="#accessing-the-instructions-panel" id="accessing-the-instructions-panel"></a>

To view or edit search instructions:

1. Open an existing project in ZSearch
2. Locate the **Instructions** section in the project workspace

<figure><img src="/files/6761mVj24bHvZiMYUh8L" alt=""><figcaption></figcaption></figure>

3. Click the **Instructions** icon or link

This opens the **Instructions** dialog, which displays the project’s current instructions.

<figure><img src="/files/KdlufUVZBlZE3IygPcgh" alt=""><figcaption></figcaption></figure>

#### Editing instructions <a href="#editing-instructions" id="editing-instructions"></a>

Within the **Instructions** dialog:

* The instruction text is shown in an editable text area
* You can modify the content to adjust AI behavior
* Instructions can include guidance on tone, response format, and context usage

Example instruction patterns include:

* Defining a specific role for the AI
* Requiring answers to be based strictly on project files
* Preventing the use of external or assumed information

After making changes:

* Click **Save** to apply the updated instructions
* Click **Cancel** to discard changes

Updates take effect immediately for all future interactions within the project.

#### Instruction scope and behavior <a href="#instruction-scope-and-behavior" id="instruction-scope-and-behavior"></a>

Key points to understand about instructions:

* Instructions are project-specific
* Changes affect all collaborators within the project
* Instructions apply to all AI interactions in that project
* The AI uses only the files added to the project as its knowledge base

Instructions do not affect search behavior outside the project or in other projects.

#### Relationship between instructions and project files <a href="#relationship-between-instructions-and-project-files" id="relationship-between-instructions-and-project-files"></a>

Instructions work together with project files to define the project’s AI context:

* **Project files** define what information the AI can use
* **Instructions** define how the AI should use that information

If files are added or removed from a project, the AI continues to follow the same instructions but uses the updated file set as context.

#### Best practices for writing instructions <a href="#best-practices-for-writing-instructions" id="best-practices-for-writing-instructions"></a>

* Be clear and specific about expected behavior
* Explicitly state if answers must be grounded only in project files
* Avoid ambiguous or conflicting guidance
* Update instructions as the project’s purpose evolves

Well-defined instructions help ensure accurate, consistent, and trustworthy responses.


---

# 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://docs.zbrain.ai/zbrain-documentation/zbrain-zsearch/projects-in-zsearch/editing-search-instructions-in-zsearch.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.