Knowledge Optimization

Your agent is only as good as its knowledge. This guide teaches you how to structure, organize, and maintain knowledge collections for optimal performance.

Attach a file, or add it to Knowledge?

There are two ways to give an agent a file, for two different jobs:

Attach it to a message when the agent needs a specific file for the task in front of it — a spreadsheet to analyze, a PDF to summarize, a screenshot to read. The whole file goes into the agent’s context for that conversation, and nothing is stored or indexed afterwards.
Add it to a Knowledge collection when the same information should be reusable and searchable across many chats — product docs, policies, FAQs. It’s chunked and retrieved on demand, and stays available to every conversation.

Rule of thumb: one file, one task → attach it. Information the agent should “just know” going forward → add it to Knowledge.

Attaching files in a chat

From the chat composer’s + menu you can:

Add from local files — PDFs, Office files (DOCX, PPTX, XLSX), CSV, Markdown, and text, plus images, audio, and video. Up to four files per message.
Add from Google Drive — pick files in the Google Picker, once your team has connected Google Drive. The agent gets only the files you choose.
Paste a Google Drive link — drop a drive.google.com or docs.google.com link into the composer and the file is attached for you.

The Knowledge Hierarchy

Organize your knowledge in layers:

Core Documentation - Essential product/service information
FAQs - Common questions and answers
Troubleshooting - Problem-solving guides
Examples - Real-world use cases
Updates - Recent changes and announcements

Best Practices

1. Keep It Current

Problem: Outdated information leads to wrong answers

Solution: Set up automatic syncing

When you add a source, choose a schedule under Keep it fresh. Free syncs at most weekly and Pro daily; Business and Enterprise can sync hourly.

2. Structure for Searchability

Bad Structure:

/docs
  - everything.md (10,000 lines)

Good Structure:

/docs
  /getting-started
    - quickstart.md
    - installation.md
  /features
    - feature-a.md
    - feature-b.md
  /troubleshooting
    - common-issues.md
    - error-codes.md

3. Use Clear Headings

Agents use headings to understand content structure.

Bad:

## Stuff

Some information about various things.

Good:

## How to Reset Your Password

Step-by-step guide:
1. Click "Forgot Password"
2. Enter your email
3. Check your inbox

4. Include Examples

Without Examples:

Use the API to create users.

With Examples:

## Creating Users via API

Example request:
\`\`\`bash
curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer TOKEN" \
  -d '{"name": "John", "email": "john@example.com"}'
\`\`\`

Example response:
\`\`\`json
{
  "id": "user_123",
  "name": "John",
  "email": "john@example.com"
}
\`\`\`

5. Remove Duplicates

Duplicate information confuses agents.

Check for:

Same content in multiple files
Outdated versions of documents
Conflicting information

Solution: Use a single source of truth for each topic.

Content Quality Checklist

For each document in your knowledge:

Optimization Techniques

Semantic Chunking

Break large documents into logical sections:

# Product Overview

## What is it?
[Brief description]

## Key Features
[Feature list]

## Use Cases
[Real-world examples]

## Getting Started
[Quick start guide]

Each section can be retrieved independently.

Metadata Tags

A short header with the topic and its keywords puts those words in the text that is searched:

---
title: Password Reset Guide
category: troubleshooting
tags: [password, login, security]
difficulty: beginner
last_updated: 2026-04-01
---

Cross-Referencing

Link related topics:

For more information, see:
- [Roles & Permissions](/account/roles/)
- [Security](/security/)
- [API Authentication](/api/authentication/)

Common Mistakes

❌ Mistake 1: Too Much Content

Problem: 10,000-page knowledge overwhelms the agent

Solution: Start with essentials, add more as needed

Priority Order:

Most frequently asked questions
Core product features
Common troubleshooting
Deep features
Edge cases

❌ Mistake 2: Unstructured Text

Problem: Wall of text without headings or formatting

Solution: Use clear structure with headings, lists, and examples

❌ Mistake 3: Stale Content

Problem: Information from 2 years ago that’s no longer accurate

Solution: Regular audits and automatic sync

❌ Mistake 4: Missing Context

Problem: “Click the button” (which button?)

Solution: Be specific and include screenshots

Performance Metrics

Track these metrics to optimize your knowledge:

Metric	Target	How to Improve
Answer Accuracy	> 90%	Add more examples, clarify ambiguous content
Retrieval Speed	< 1s	Reduce document size, improve structure
Coverage	> 80%	Add content for unanswered questions
Freshness	< 7 days	Enable automatic sync

Sources

Supported Sources

Notion

Sync the pages shared with your Notion connection, or one database.

Confluence

Sync a space, its pages and their child pages.

Google Drive

Sync the files you pick. Supports Docs, Sheets, Slides.

GitHub

Index the Markdown, text and CSV files in a repository.

File Upload

Upload PDF, DOC, DOCX, and TXT files directly.

Web Crawl

Crawl your website or documentation site.

ServiceNow

Sync knowledge articles or incidents.

Maintenance Schedule

Daily

Monitor unanswered questions
Review agent conversations
Flag outdated content

Weekly

Sync knowledge collections
Update FAQs based on new questions
Add examples for common issues

Monthly

Audit entire knowledge
Remove duplicates
Reorganize if needed
Update metadata

Quarterly

Major content review
Archive outdated content
Plan new content additions

Deep Techniques

Version Control

Track changes to your knowledge:

# Tag versions
v1.0 - Initial launch
v1.1 - Added troubleshooting section
v1.2 - Updated API examples

A/B Testing

Test different content structures:

Version A: Long-form guides
Version B: Short FAQs
Measure: Which gets better results?

Feedback Loop

Improve based on usage:

Agent can’t answer → Add to knowledge
Wrong answer → Update content
Frequent question → Add to FAQs
Positive feedback → Keep as is

Resources

Next Steps

Audit your current knowledge
Implement the structure recommendations
Set up automatic syncing
Monitor performance metrics
Iterate based on results

Set up your knowledge →