Tags & Custom Metadata
Access Tags decide who can see a document. Custom Metadata describes what the document is about. They look similar in the UI but solve different problems — do not use Access Tags as a substitute for metadata (or the reverse).
Prerequisites
| Task | You need |
|---|---|
| Create team tags | Access to My Account → Tags (team admin path for the tag catalog) |
| Assign tags to people | Permission to edit members in Team Management |
| Apply Access Tags on a document | Permission to edit the knowledge base resource |
| Edit Custom Metadata on a document | Permission to edit the resource |
| Let an agent filter by searchable metadata | Knowledge Base toolkit on the agent with Custom Metadata Filtering enabled |
Access Tags
What they are
Tags control who can see a document — a badge system. A document can require a badge to open it, or block anyone holding a certain badge.
Tags exist for visibility and access control. A tag can be named after a department or topic, but that is just a label — its only real effect is who can (or cannot) see the document. It does not organize, categorize, or filter documents the way Custom Metadata does.
End-to-end setup
- Create the tag catalog in My Account → Tags (for example
HR-Only,Sales-Team,Finance-Confidential). - Assign tags to people when editing a team member (same place you change role). Each member can hold one or more tags.
- Apply tags on documents from the resource detail page → Access Tags → Edit Access Tags (opens Document Access Control).
Modes on a document
| Mode | UI label | Effect |
|---|---|---|
| Allow | Allow Only | Users must hold at least one of the listed tags to see the document |
| Block | Allow None | Users who hold any of the listed tags are denied, even if they would otherwise have access |
Rules of thumb:
- If a document has no Access Tags, everyone who can access the project can see it — tags only restrict once applied
- When both modes could apply to the same person, a block always wins over an allow
- The document modal reminds you: create tags under My Account → Tags if the catalog is empty
Example: Upload a salary review and set Allow Only: HR-Only. A user with the
HR-Onlytag can open and search it; anyone without that tag will not see it in search results or chat answers.
Note: Access Tags govern what shows up in AI-powered search and chat answers (including EKB Runtime
search_knowledgeandask_*as that user). Treat them as an added layer on top of — not a substitute for — correct project-level access.
When to use Access Tags
- Confidential or sensitive documents (HR records, payroll, legal, financial data)
- Department-specific material that should not be visible company-wide inside the same project
- Documents meant only for a specific role or clearance
For everyday organizing — sorting by department, topic, or type — use Custom Metadata below.
Custom Metadata
What it is
Custom Metadata attaches descriptive labels to a document — facts like Department: Engineering, Author: Jane Smith, Version: 2.1. It answers "what is this document about?" rather than "who can see it?"
On the resource Details tab, Custom Metadata appears in two sections:
| Section | UI label | Role |
|---|---|---|
| Auto / connector fields | AI-Searchable | Auto-populated (for example from SharePoint library columns) and indexed for agent retrieval |
| Manual fields | User-Defined | Added with Add Field — for reference only; not searchable by agents |
Two types at a glance
| User-Defined (manual) | AI-Searchable (auto-captured) | |
|---|---|---|
| How it's added | Add Field on the document | Captured when importing from a connected source that already has columns/fields |
| Filters search results? | No — reference only | Yes — this is the type that can narrow search |
| Shown as | User-Defined | AI-Searchable |
Agent: Custom Metadata Filtering
On an agent’s Knowledge Base toolkit configuration, enable Custom Metadata Filtering (enable_metadata_filtering) to:
- Add a
metadata_filterparameter to knowledge search tools - Add a tool that lists available metadata fields/values
This is how agents intentionally limit retrieval to documents with specific searchable metadata (for example SharePoint columns). Matching is exact, not fuzzy — keep values consistent (Engineering, not Eng / eng. dept).
Flat fields only
Metadata fields are flat, single-level labels — not nested categories. You can have Department: Engineering, but not a single nested structure Department → Team → Sub-team.
If a second level of detail is needed, add a second field (for example Sub-Team alongside Department). Both can still be combined when filtering.
Quick comparison
| Access Tags | Custom Metadata | |
|---|---|---|
| Purpose | Controls who can see a document | Describes what a document is about |
| Best used for | Confidentiality and access control | Organization and precise search |
| Affects search / chat | Yes — restricted docs are hidden for users without access | Only AI-Searchable fields narrow retrieval (with filtering enabled on the agent) |
| Set up by | Tag catalog + member assignment + document Edit Access Tags | Add Field, or auto-capture on connector import |
| Catalog location | My Account → Tags | Per document (and source system columns) |
Troubleshooting
| Symptom | What to check |
|---|---|
| Edit Access Tags shows no tags | Create tags under My Account → Tags first |
| User still sees a restricted doc | Confirm the user’s assigned tags, document Allow Only / Allow None, and that block-wins rules are not inverted from what you intended |
| User cannot see a doc they should | They may be missing an Allow Only tag, or hold an Allow None tag |
| Agent does not filter by department | Confirm fields are AI-Searchable, values are consistent, and Custom Metadata Filtering is enabled on the KB toolkit |
| Manual metadata never affects answers | Expected for User-Defined fields — they are reference only |