> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceflow.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Querying the knowledge base
To give your agent access to the knowledge base, open the **Agent** and make sure the **knowledge base** toggle is on in [system tools](/documentation/build/tools/system-tools). When on, your agent will automatically use this tool when it needs information to answer a question.
When on at the agent level, individual [playbooks](/documentation/build/playbooks) can also query the knowledge base. You can override query settings at the playbook level without impacting the agent or other playbooks.
## Configuring the knowledge base tool
When you enable the knowledge base system tool in your agent, you can configure how it queries your content.
### LLM description
Describes what this tool does and when the agent should use it. By default this is pre-filled with an opinionated description, however, you can reset it to a simpler default, or override it to your use-case. You can also add examples in your agent or playbook instructions showing when to use — or avoid — this tool for better retrieval accuracy.
```text Opinionated default we apply to new projects theme={null}
Use this tool when answering any question about your company, product, service,
or purpose, unless the answer has already been retrieved in the current
conversation.
Never answer these questions from your own knowledge - only use information
retrieved from this tool or web search. Before searching, reformat the user's
query for retrieval by extracting key terms and intent, stripping filler, and
including relevant conversation context.
If no results are found, try web search (if available) before saying you don't
have information. Never mention the knowledge base, or your use of it, to users.
```
```text Simple default you can reset to theme={null}
Searches an external knowledge base to retrieve relevant information,
supplementing or replacing the language model's internal context.
```
### Custom query
By default, the agent uses the user's last message as the search query. Use a custom query to override this — useful when you want to search on a specific variable or a reformulated version of the user's input. To insert a variable, type `{` in the input.
### Query re-writing
When enabled, the model rewrites the user's last message before searching based on your instructions — improving retrieval for conversational or ambiguous inputs. Useful when users don't phrase questions the way your content is written.
```text Query re-writing example theme={null}
Search for the underlying user intent rather than the user's exact words.
For example:
- "it won't let me log in" = "login error troubleshooting"
- "my thing never showed up" = "missing order or delivery issue"
- "how much is it" = "pricing and plan information"
```
### Chunk limit
Controls how many content chunks are returned per query (1–10, default 3). Higher values return more context but increase latency and token usage. Start at 3 and increase if the agent is missing relevant information.
### Meta data filtering
Unfamiliar with adding meta data in the knowledge base? [Learn more](/documentation/build/Importing-data-sources)
Filter which data sources are queried based on metadata tags. Useful when you have content for different plans, regions, or product lines and want to make sure the agent only retrieves what's relevant for the current user.
Meta data filtering lets you apply values manually, or let the agent/playbook apply query values at runtime based on the conversation history.
You can add a variable to the default value field by typing`{` .
### Tool messages
Customize what the user sees while the knowledge base tool is running. You can set scripted messages for four states:
* **Start** — shown when the tool begins querying
* **Complete** — shown when results are returned
* **Fail** — shown when the query returns nothing or errors
* **Delay** — shown if the query takes longer than expected (you set the delay threshold)
Each state supports multiple message variants — the agent picks one randomly to avoid repetition. You can also set conditional variants that trigger based on variables or context, giving you fine-grained control over what the user sees depending on the situation.
### Show source URL(s)
This feature is only available in **chat** projects.
When enabled, the agent includes the source URL alongside its response so users can verify or read more. Recommended for help centers and documentation.
## Developers
The Knowledge base API gives you programmatic access to the documents that power your agent’s knowledge base. You can use it to [create](https://v4-docs.voiceflow.com/api-reference/kbpublicapidocument/create-document), [retrieve](https://v4-docs.voiceflow.com/api-reference/kbpublicapidocument/get-document), [update](https://v4-docs.voiceflow.com/api-reference/kbpublicapidocument/update-document-metadata), and [delete](https://v4-docs.voiceflow.com/api-reference/kbpublicapidocument/delete-document) documents, as well as manage their metadata and individual chunks.