> ## Documentation Index
> Fetch the complete documentation index at: https://anam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect knowledge tools

> Connect knowledge folders to an Anam persona through search tools, choose the intended scope, and monitor knowledge tool calls.

## Overview

Knowledge tools let your persona search uploaded documents and use retrieved passages in its answers through Retrieval-Augmented Generation (RAG). Instead of relying only on the LLM's training data, your persona can access your organization's specific documentation, policies, and knowledge base.

Use this guide to connect your uploaded documents to a persona. Before selecting folders, [check the knowledge scope](https://anam.ai/docs/personas/knowledge/setup.md#set-the-knowledge-scope) for its audience. Every document in the selected folders should be appropriate for that persona.

## Prerequisites

Before creating knowledge tools, you need:

* Knowledge folders created (see [Set up your knowledge base](https://anam.ai/docs/personas/knowledge/setup.md))
* Documents uploaded and in READY status
* Basic understanding of RAG concepts (see [Knowledge overview](https://anam.ai/docs/personas/knowledge/overview.md))

## Creating a knowledge tool

Knowledge tools are saved to your organization's tool library, so one tool can be attached to several personas.

### The quickest path

The first time you upload documents to a persona, Anam creates the knowledge tool for you. On the [Prompt tab](https://lab.anam.ai/build?tab=prompt), open the **Knowledge** card and select **Upload documents**. Once the upload finishes, a tool named after the persona is created, pointed at the new folder, and attached to the persona draft.

Select **Publish** before creating a session with this persona's `personaId` — until you do, those sessions run with the persona's previously published tools. See [when you need to publish](#when-you-need-to-publish).

You only need the steps below to control the tool's name, its description, or which folders it searches.

### Creating one yourself

**1. Open the tool editor**

Go to the [Tools tab in Anam Lab](https://lab.anam.ai/build?tab=tools) and select **Add tool**.

The menu offers **Client tool** and **Server tool** — there is no knowledge entry, so pick either one and change the type in the next step.

**2. Set the type to Knowledge**

In the editor, set **Type** to **Knowledge**, then fill in:

* **Name**: `search_product_docs` (snake\_case)
* **Instructions**: when the persona should search — this is what the model reads to decide
* **Knowledge folders**: select every folder this tool may search

**3. Save and publish**

Select **Create tool**, then **Publish** the persona.

> [!TIP]
>
> The tool is saved to your tool library with a unique ID, and publishing makes it available to sessions created with this persona's `personaId`.

**4. Use in session**

Create a session using the persona ID:

```javascript theme={"system"}
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    personaConfig: {
      personaId: "your-persona-id", // Published tools loaded automatically
    },
  }),
});
```

To create a tool through the API instead, see the knowledge tool configuration in the [tools overview](https://anam.ai/docs/personas/tools/overview.md#knowledge-tools-rag).

### Write the instructions

When deciding whether to call a knowledge tool, the model sees the tool's instructions but not its folders, filenames, or document contents. Write instructions that tell the model when to search. The field is labeled **Instructions** in the Lab and `description` in the API, and it holds up to 1024 characters.

Name the subjects your folders actually cover, in the words a user would use, and say when not to search.

| Don't | Do |
| - | - |
| Describe the mechanism: “Searches the knowledge base.” | Describe the subjects: “Searches product documentation and billing FAQs.” |
| List document titles the user will never say. | List topics in the user's words, such as refunds rather than `returns-policy-v4.pdf`. |
| Leave the boundary unstated. | Say what the folders do not cover, especially where another tool does. |
| Give two knowledge tools the same generic description. | Say what distinguishes each one; the model uses these descriptions to choose between them. |

**Example**

**Don't:** “Search the knowledge base for relevant information.”

**Do:** “Search product documentation and billing FAQs for questions about product features, installation steps, pricing tiers, invoices, and refunds. Do not use it for a customer's own account details, such as their current balance or open tickets.”

The first does not tell the model which questions match the tool. The second helps it recognize a billing question as something these folders can answer and a balance inquiry as something they cannot.

> [!WARNING]
>
> When the Lab creates a knowledge tool for you on first upload, it writes a generic description that names no subject. Replace it with one describing your own content, or the model is choosing when to search from a description that fits any knowledge base.

For naming conventions shared by all tool types, see [Write clear descriptions](https://anam.ai/docs/personas/tools/overview.md#write-clear-descriptions). To tell the persona how to handle results and failures, see [Tool calling definitions](https://anam.ai/docs/personas/llms/prompting-guide.md#tool-calling-definitions).

### How many tools

Start with one tool covering the folders a persona needs, and split it only when the model has to choose between clearly different bodies of knowledge — product documentation versus billing policies, say. A separate tool per folder gives the model a sharper choice; a single tool over related folders keeps that choice simple. Group folders the same way you [scoped them](https://anam.ai/docs/personas/knowledge/setup.md#set-the-knowledge-scope) in the first place.

### When you need to publish

Attaching a tool changes the persona, and persona changes are staged as a draft until you publish. Uploading documents does not change the persona draft, so it does not require publishing.

| What you changed | Publish needed? |
| - | - |
| Attached a new knowledge tool | Yes — sessions created with `personaId` use the previously published tools until you publish |
| Changed which folders an existing tool searches | No — new sessions for every persona using that tool load the updated folders |
| Uploaded new or replacement documents | No — each document becomes searchable when it reaches `READY` |
| Deleted documents | No — deletion removes the document from search immediately |

## How knowledge tools work

When the AI needs information to answer a question, it uses a knowledge tool to search your documents.

**1. User asks a question**

User: "How do I authenticate API requests?"

**2. AI decides to search**

The AI determines the question requires information from your documentation and automatically formulates a search query.

> [!NOTE]
>
> The AI looks for the semantic meaning behind the user's question, not just literal keywords.

**3. System finds relevant content**

The system searches the folders associated with the tool and retrieves the most relevant snippets from your documents.

**4. AI generates a response**

The AI uses the retrieved information to compose an answer.

"To authenticate API requests, you'll need to include your API key in the Authorization header like this: `Authorization: Bearer <your API key>`. You can get an API key from your dashboard."

> [!TIP]
>
> The user receives an answer grounded in your specific documentation.

## Monitoring knowledge tool calls

Knowledge tool calls emit lifecycle events on the client that you can use for logging or analytics. Use `toolType` and `toolSubtype` to filter for knowledge-specific events:

```javascript theme={"system"}
import { AnamEvent } from "@anam-ai/js-sdk";

anamClient.addListener(AnamEvent.TOOL_CALL_STARTED, (event) => {
  if (event.toolType === "server" && event.toolSubtype === "knowledge") {
    console.log(`Knowledge search started: ${event.toolName}`);
  }
});

anamClient.addListener(AnamEvent.TOOL_CALL_COMPLETED, (event) => {
  if (event.toolType === "server" && event.toolSubtype === "knowledge") {
    console.log(`Knowledge search completed: ${event.toolName} in ${event.executionTime}ms`);
  }
});

anamClient.addListener(AnamEvent.TOOL_CALL_FAILED, (event) => {
  if (event.toolType === "server" && event.toolSubtype === "knowledge") {
    console.error(`Knowledge search failed: ${event.toolName} - ${event.errorMessage}`);
  }
});
```

> [!TIP]
>
> See the [Events SDK Reference](https://anam.ai/docs/javascript-sdk/reference/events.md#tool-call-events) for the full list of tool call event payloads and types.

## Test the connection

Start a fresh session and ask a question that requires your uploaded reference material. Check that the intended knowledge tool runs, then follow [Test your knowledge base](https://anam.ai/docs/personas/knowledge/testing.md) to inspect passages and evaluate the answer, including exceptions and missing details.

When replacing a folder, check every knowledge tool attached to the persona so that another tool does not retain access to the old material. See [Replace an existing document](https://anam.ai/docs/personas/knowledge/uploading-documents.md#replace-an-existing-document).

## Next steps

> [card] [Set up your knowledge base](https://anam.ai/docs/personas/knowledge/setup.md)
>
> Create folders and upload documents

> [card] [Client Tools](https://anam.ai/docs/personas/tools/client-tools.md)
>
> Trigger UI actions with client tools

> [card] [Webhook Tools](https://anam.ai/docs/personas/tools/webhook-tools.md)
>
> Integrate external APIs

> [card] [API Reference](https://anam.ai/docs/api-reference/tools/create-tool.md)
>
> Complete API documentation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.