# Pointers

Train your agent to connect user questions to the right knowledge base documents, even when phrasing doesn't match.

## What Are Pointers?

Pointers are a training mechanism in Foldspace that create an explicit link between a question or prompt and a specific knowledge base document. They help your Agent understand not just the obvious connections between topics and content, but also the indirect, implicit ones — including internal terminology, product-specific language, and glossary variations.

Think of Pointers as teaching your Agent which document to reach for when a user asks something — even when the phrasing doesn't perfectly match the document's title or content.

:::caution[You won't need these often]
Pointers are a precision tool for **rare cases**, not part of normal setup. Out of the box the agent already retrieves the right content by semantic similarity for the large majority of questions. Reach for a Pointer only when there's genuine **ambiguity** — between two sources that could both match, or between a user's term and your product's term — and the agent picks wrong. If answers are simply missing, that's a [Knowledge Base](/user-guides/knowledge-base/) gap, not a Pointer problem.
:::

<Mermaid chart={`flowchart LR
    Q["User question<br/>'How do I give my teammate admin access?'"] --> P["Pointer"]
    P --> D["Knowledge Base document<br/>'User Permissions & Roles'"]
    style Q fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
    style P fill:#1842ef,stroke:#1842ef,color:#ffffff
    style D fill:#d1fae5,stroke:#059669,color:#0a0e1a
`} />

## Why Pointers Matter

Semantic search works well for direct questions. It breaks down in two specific situations, and those are the only times a Pointer earns its keep:

- **Ambiguity between terms** — Your product uses a word the user wouldn't. Someone asking "how do I define my audience?" needs the *Segments* article, even though "segments" never appears in their question.
- **Ambiguity between sources** — Two documents both look like plausible matches and the agent keeps choosing the less helpful one. A Pointer breaks the tie explicitly.

In those cases you're curating the retrieval layer so your Agent responds with the right content, not just the closest match. Everywhere else, leave retrieval to do its job.

## Where to Add Pointers

There are two places in Foldspace where you can manage Pointers:

### From the Document (Pointers Tab)

When editing any knowledge base document, navigate to the **Pointers** tab. Here you can add questions that should map to this document. Each question you add trains the Agent to associate that phrasing — or anything semantically similar — with this content.

Use this view when you're building or reviewing a document and want to proactively define how users might ask about it.

### From the Agent Conversations

Inside a specific conversation you can click on the right side of the user prompt (the icon is a sliders/filter icon — three horizontal lines with small adjustment handles) and add content and pointers. This area is titled **Agent Playground** where you can link questions directly to documents in a training-oriented interface. You can:

- Enter one or more question variants in the Questions panel
- Select the relevant knowledge base document in the Documents panel
- Create new internal article
- Save to train the Agent on that connection

Use this view when you're testing your Agent, discover a gap in its responses, and want to immediately correct it by linking a question to the right document.

<Mermaid chart={`flowchart TD
    subgraph Proactive
        A["Edit KB article"] --> B["Open Pointers tab"]
        B --> C["Add question variants"]
    end
    subgraph Reactive
        D["Review conversation"] --> E["Spot a gap"]
        E --> F["Open Agent Playground"]
        F --> G["Link question → document"]
    end
    style A fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
    style D fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
    style C fill:#d1fae5,stroke:#059669,color:#0a0e1a
    style G fill:#d1fae5,stroke:#059669,color:#0a0e1a
`} />

## Best Practices for Writing Pointers

- **Cover phrasing variants** — Add multiple phrasings of the same question. Users rarely ask things the same way twice.
- **Include your product's terminology** — If your product uses specific terms that aren't industry-standard, add questions that reflect how users describe the same concept in plain language.
- **Think in use cases, not just keywords** — Write questions the way a user would genuinely ask them mid-workflow, not how you'd title a help article.
- **Prioritize implicit gaps** — Pointers are most valuable where your document titles and content don't obviously match the user's intent. Obvious matches usually don't need Pointers.

## Example

**Document:** _Managing User Roles and Permissions in [Your product]_

Pointers you might add:

- *how do I give my teammate admin access?*
- *where can I change what a user can see?*
- *how do I restrict access to certain features?*
- *can I set different permission levels per workspace?*

These Pointers ensure that regardless of how a user phrases their intent, the Agent surfaces the right document.