Scoping Knowledge: All Documents vs Hand-Picked Sources Per Agent

Macha gives you that control directly. Knowledge sources live at the org level, but every agent decides how much of each source it sees: All documents, or a hand-picked subset. This is the difference between a billing agent that quotes your refund policy verbatim and one that wanders into an outdated pricing PDF because it was technically "in the knowledge base." This post is a deep dive on how that scoping works, when to use each mode, and the trade-offs nobody puts in the marketing copy.

Macha is the AI agent layer that sits on top of the helpdesk you already run — Zendesk, Freshdesk, Gorgias, Front — so everything below is about shaping what your agents know, not replacing where your tickets live.

The two-level model: shared library, per-agent scope

Knowledge in Macha is organized on two levels, and getting the mental model right makes everything after it obvious.

Level one — the source library. You add a data source once: upload a PDF, spreadsheet, or document; crawl a website; or connect a live source like Google Docs, Notion, or Confluence. Small files get injected straight into the agent's prompt; larger ones are chunked, embedded, and searched on demand. Live connector sources are read in real time, so when someone edits the Notion page, the agent sees the new version on the next ticket — no re-uploading. Connecting Confluence (like Google and Notion before it) automatically creates a source for you.

Level two — per-agent scope. A source existing in your library doesn't mean every agent drinks from it. Each agent attaches the sources it needs, and for each attached source, you set its scope: all of it, or specific documents. That's the whole idea — centrally managed knowledge, tailored usage per agent, with zero content duplication. You never copy the returns policy into three different agents; you attach one source three times and scope it differently each time.

This is the same pattern serious platforms have converged on. Microsoft 365 Copilot's declarative agents are configured by attaching a defined set of knowledge sources per agent — each agent grounds only on the sources you give it (specific SharePoint sites and folders, named files, individual website URLs), not your whole tenant. Several other support-AI tools take a similar shape, scoping a connector down to a chosen space, folder, or document set rather than the entire connected workspace. Macha's version is deliberately simple: a binary All documents / Selected choice on every source row.

All documents vs Selected: the scope toggle

On every data source attached to an agent, there's an inline toggle: All documents or Selected. As of the April 3 update it's a one-click switch right on the source row — you no longer expand the source to change its scope.

• All documents — the agent can retrieve from everything in that source, now and in the future. Add a new page to the connected Notion workspace and the agent picks it up automatically. This is the "keep up with me" mode.
• Selected — you hand-pick the exact documents the agent may use. The agent is blind to everything else in that source, including anything added later, until you explicitly include it. This is the "stay in your lane" mode.

The toggle is per source per agent, which is the important nuance. The same Google Drive source can be All documents for your internal ops agent and Selected → [Refund Policy, Shipping SLA] for your customer-facing WISMO agent. One library, two very different blast radii.

When "All documents" is the right call

• The source is already curated. A dedicated "Customer Help Center" Notion space or a tightly maintained Confluence space where every page is publishable to customers. If everything in the source is safe to surface, scoping it down just creates maintenance work.
• You want new content live automatically. Marketing ships a new returns FAQ page; with All documents the support agent answers from it the moment it's saved — no one has to remember to add it to an allow-list.
• Internal agents over trusted corpora. An agent that helps your own team triage tickets can usually see the whole runbook space.

When "Selected" earns its keep

• The source is mixed. A shared Drive that holds the customer refund policy and the internal margin spreadsheet and last quarter's draft pricing. You want exactly two of those documents in front of a customer agent and none of the rest.
• Compliance or accuracy boundaries. Legal-approved language only. Pick the approved doc, exclude the drafts, and the agent physically cannot retrieve the unapproved version.
• You're debugging hallucinations. When an agent cites the wrong doc, narrowing scope to the handful of sources it should use is the single most effective fix — far more reliable than rewording the prompt.

A worked setup: two agents, one library

Say you run three sources: a Help Center site crawl (all customer-safe), a Google Drive folder (mixed — policies plus internal finance), and a Notion space for internal SOPs.

The customer-facing agent answers shipping and refund questions from approved language and literally cannot reach the finance spreadsheet or internal SOPs. The internal agent sees everything because its audience is your own team. Same three sources, scoped two ways, no duplicated content. Change the refund policy once in Drive and both the document and the customer agent's answer update — because the agent points at the live source, not a copy.

This is also where Macha's sub-agents matter: a top-level router can delegate to specialist sub-agents that each carry their own narrowly scoped knowledge, so a billing question reaches the agent that only sees billing docs.

How scope interacts with retrieval

A practical detail worth knowing: scope changes what's eligible for retrieval, not how retrieval works. Within whatever's in scope, small files may be injected into the prompt directly while larger ones are chunked, embedded, and searched semantically on demand. Narrowing scope therefore does two useful things at once — it removes wrong-but-plausible documents from the candidate set, and it keeps the retrieval space tight, which tends to surface the right chunk higher. Tighter scope is often the cheapest accuracy win available, because every credit you spend is a per-action cost and you'd rather spend it reasoning over the right three documents than ranking the wrong thirty.

Watch-outs and when NOT to over-scope

Scoping is powerful, which means it's also possible to overdo it. A few honest cautions:

• Selected mode is a manual allow-list. New documents added to that source after you set the scope are not automatically included — that's the point, but it also means a "Selected" agent can silently go stale if someone publishes a new policy and forgets to add it. If your content changes weekly, All documents on a curated source is lower-maintenance than babysitting a hand-picked list.
• Don't scope around a messy library. If you find yourself hand-picking five documents out of a forty-document source for every agent, the real fix is to split that source (or restructure the underlying Drive/Notion space) so "All documents" is safe. Scope is a control, not a substitute for organizing your knowledge.
• Plan limits are real. The number of knowledge sources and agents you can run is capped by plan — Starter is the tightest, Professional roomier, Enterprise unlimited. Scoping doesn't change those caps; see the pricing page for the current limits before you architect a dozen narrowly-scoped agents.
• **Scope is not access control for people.** It governs what an agent retrieves, not who on your team can view a document. Don't use it as your data-governance layer for human permissions — use your source-system permissions for that.

How to set it up

1. Add your sources once in the data sources library — upload files, crawl a site, or connect Google Docs / Notion / Confluence as live sources. (Connecting Confluence auto-creates the source; the Google Picker lets you select Docs and Sheets natively instead of pasting IDs.)
2. Open an agent and attach the sources it needs on its Knowledge tab.
3. For each attached source, set the inline toggle to All documents or Selected.
4. If Selected, hand-pick the specific documents, save, and test the agent against a real ticket to confirm it only cites what you intended.

The whole loop takes minutes, and the test step is the one people skip and shouldn't — running a real ticket through the agent is how you prove scope is doing what you think.

FAQ

Is knowledge scoped globally or per agent? Per agent. Sources live in one shared library, but each agent sets its own scope (All documents or Selected) on every source it attaches. The same source can be wide-open for one agent and narrowed to two documents for another.

Does "Selected" automatically include new documents? No — that's by design. Selected is an explicit allow-list. New documents added to the source later aren't included until you add them. If you want new content live automatically, use All documents on a curated source.

Do live sources update without re-uploading? Yes. Google Docs, Notion, and Confluence connect as live sources read in real time. Edit the underlying document and the agent sees the change on the next run — no re-upload, no re-index step on your end.

Can different agents use the same source with different scopes? Yes — that's the core benefit. Attach one source to many agents and scope each independently. No content is duplicated.

Does scoping change the cost? Credits are charged per AI action, not per document in scope. Tighter scope won't directly cut your bill, but by surfacing the right context it tends to reduce retries and wrong answers — which is where wasted spend actually hides.

Start scoping

If your agents are confidently citing the wrong document, you don't need a bigger model — you need tighter scope. Start a 7-day free trial, no credit card required, add your sources once, and give each agent exactly the documents it should answer from. Read the data sources docs for the full walkthrough, or browse the blog for more on building accurate agents on top of your helpdesk.

Written by Abbas (Customer Support & AI, Macha) · Reviewed by Ankeet Guha (Co-founder & CTO) · Published 2026-06-24 · Last updated 2026-06-24.