> ## 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.
# Referencing tools in prompts
> Insert tools, system tools, playbooks, and workflows directly into your instructions so the agent knows exactly which one to use and when.
A reference is a link to something your agent can use, placed directly in a sentence of your instructions. Instead of writing the name of a tool and hoping the agent matches it up, you point at the real thing.
References remove a whole category of small errors. A typo in a tool name, a tool that was renamed last week, two playbooks with similar names - none of those trip up an agent reading a reference, because the reference points at the resource itself rather than at whatever you typed.
You can reference tools, system tools, playbooks, and workflows anywhere the [editor](/documentation/build/editor/overview) appears: the [global prompt](/documentation/build/global-prompt), your [agent instructions](/documentation/build/instructions), and inside any [playbook](/documentation/build/playbooks).
## Adding a reference
Type / where you want the reference to appear. The menu opens with a **Reference** section listing **Tools**, **System tools**, **Playbooks**, and **Workflows**.
A category with nothing in it appears greyed out and can't be selected.
Select the category you want. The menu opens a searchable list of everything available in that category.
Start typing to narrow the list, then press Enter or click to insert. The reference appears inline as a small chip showing the resource name and its icon.
You can also filter from the top level. Typing part of a category name after the slash, such as `/work`, narrows the menu down to **Workflows**, and pressing Enter opens it.
Adding a reference attaches that resource to your agent automatically, so there is no separate step to make it available. Playbooks and workflows are attached at the agent level, meaning they become reachable from anywhere in the agent.
## What you can reference
| Category | What it includes |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tools** | [API tools](/documentation/build/tools/api-tool), [Function tools](/documentation/build/tools/function-tool), [MCP tools](/documentation/build/tools/mcp-tool), and [integrations](/documentation/build/tools/overview) such as Zendesk, Salesforce, Shopify, and HubSpot |
| **System tools** | Voiceflow's built-in capabilities, like the knowledge base and web search |
| **Playbooks** | Any [playbook](/documentation/build/playbooks) in this agent |
| **Workflows** | Any [workflow](/documentation/build/workflows) in this agent |
Tools of every kind are grouped into one searchable list, so you don't need to remember whether something was built as an API tool or a function.
## Creating tools before you reference them
The reference menu selects from what already exists. It does not create anything.
If the tool, playbook, or workflow you want isn't in the list, create it first, then come back to your instructions and reference it. Once it exists, it appears in the menu straight away.
Connect to any REST API with a custom request.
Run custom JavaScript logic mid-conversation.
Connect an MCP server and expose its tools.
Pre-built connectors for Zendesk, Salesforce, Shopify, and more.
Playbooks and workflows work the same way. Create them from the **Agent** tab, from a [playbook step](/documentation/build/steps/playbook) or [workflow step](/documentation/build/steps/workflow), or from the **Playbooks** and **Workflows** tabs in the sidebar.
Variables and secrets are the exception. Those can be created inline while you write, without leaving the editor.
## Referencing system tools
System tools are built into Voiceflow and need no setup. Which ones appear in the menu depends on your agent, since some are specific to chat or voice:
* **Knowledge base** - search your [knowledge base](/documentation/build/importing-data-sources) for an answer
* **Buttons** - offer clickable options instead of asking the user to type
* **Cards** - show a rich card with a title, description, and image
* **Carousels** - show several cards in a scrollable row
* **Call forward** - transfer the call to a phone number or SIP address
* **Web search** - look up current information on the web
* **Skip turn** - stay quiet and wait rather than replying
* **End** - close the conversation
Referencing a system tool is useful when you want to be specific about ordering. For a full description of each tool and how to configure its trigger, see [system tools](/documentation/build/tools/system-tools).
In the editor a reference shows as a chip with the tool's name. Read as plain text, the same instructions look like this:
```text Example theme={null}
# Answering product questions
Search @system:knowledgeBaseTool before anything else. If it
returns nothing useful, fall back to @system:webSearchTool and
tell the customer where the answer came from.
```
You don't need to type these. Insert them with / and the editor writes the right one for you.
## Editing and removing a reference
Click any reference to open its menu.
From here you can:
* **Swap it** for a different resource by picking another from the list, which replaces the chip in place
* **Open it** by hovering the row and clicking **Edit**, which takes you to that tool, playbook, or workflow
* **Remove it** by pressing Backspace or Delete
Renaming a resource elsewhere updates every reference to it automatically, so there is nothing to go back and fix.
## When a reference goes missing
If a reference turns into a **Missing reference** warning, the resource it pointed at is no longer available to this agent. That usually means it was deleted, or it was removed from the agent's tools.
The warning is safe to leave while you sort it out, and clicking it opens the same menu so you can point it somewhere else or remove it. Variables and secrets behave the same way, showing **Missing variable** or **Missing secret**.
Fix a missing reference by either recreating the resource, or selecting a replacement from the menu.
## Referencing variables and secrets
Type \{ to insert a [variable](/documentation/build/data/variables) or a secret. The menu has a tab for each, a search field, and a **Create variable** button if the one you need doesn't exist yet.
Variables appear as coloured chips and are replaced with their live value when the agent runs, so `{customer_name}` in your instructions becomes the customer's actual name in the conversation.
A few built-in variables are greyed out and can't be inserted into a prompt, including `vf_now`, `vf_time`, `last_utterance`, and `vf_memory`. Their values change on every turn, which prevents the model from reusing its cache and makes your agent slower and more expensive.
Copying instructions into a plain text document writes each reference out in its `@type:id` form, and each variable as `{name}`. Pasting that text back into the editor turns them into working references again, so you can move instructions between agents without rebuilding them by hand.
## Next steps
Format as you type, and paste markdown from anywhere.
Every shortcut for formatting, blocks, and menus.