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

1. Create the tag catalog in My Account → Tags (for example HR-Only, Sales-Team, Finance-Confidential).
2. Assign tags to people when editing a team member (same place you change role). Each member can hold one or more tags.
3. 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-Only tag 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_knowledge and ask_* 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_filter parameter 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

Related

• Tags (team catalog)
• Knowledge Base overview
• EKB Runtime