Skip to content

docs: clarify AI agent knowledge document file types and relevance #679

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify AI agent knowledge document file types and relevance #679

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions guides/ai-agents/best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ When you upload a document, Lightdash reads it and writes a short summary of wha
A few things worth knowing:

- **The agent decides when to open a document.** If your document is never being used, the summary probably isn't specific enough about what it's for. Renaming the document or making its purpose clearer in the content usually fixes it.
- **Each document gets a relevance rating against your project.** After uploading, check the relevance card. If a document is rated low or unrelated, the agent has been told not to rely on it for data questions — you'll want to revise it, or scope it to a different agent where it's more relevant.
- **Each document gets a relevance rating against your project.** After uploading, check the relevance card. Documents are rated `high`, `medium`, `low`, or `none` against the explores the agent can see. If a document is rated low or unrelated, the agent has been told not to rely on it for data questions — you'll want to revise it, or scope it to a different agent where it's more relevant.

### What to upload

Expand All @@ -192,7 +192,7 @@ Good candidates are anything a new analyst on your team would need to read befor
### Practical tips

- **Keep documents focused and short.** Each document is capped at 20KB and the org-wide quota is 5MB, but the practical limit is much lower: a focused one-page note is consulted more reliably than a sprawling wiki export. Split large references into one document per topic.
- **Use Markdown.** `.md` and `.txt` are supported. Markdown headings and lists make summaries more accurate.
- **Use Markdown.** `.md`, `.markdown`, and `.txt` files are supported. Markdown headings and lists make summaries more accurate.
- **Name documents like a `use when` clue.** `Revenue recognition rules.md` is better than `notes.md` — the name is part of what the agent sees.
- **Scope documents per-agent.** A document uploaded for your Finance agent shouldn't pollute your Marketing agent's context. Use the per-agent access setting to keep documents relevant.
- **Re-check after big changes.** When you add new explores or rename fields, revisit the relevance rating on existing documents — `relatedExploreNames` references exact explore names and can go stale.
Expand Down
Loading