This feature lets you restrict an agent's OneDrive access to a specific set of folders or individual files. Instead of giving an agent access to everything in OneDrive, you choose exactly what it can see — down to individual files if needed.
What's new
File-level scoping — You can now pin an agent to specific files (e.g. a single
Q1-Report.xlsx), not just folders. Previously only folder-level restrictions were supported.Mixed scoping — You can scope an agent to a combination of folders and individual files in one configuration.
Auto-refreshed names — If a folder or file is renamed in OneDrive after you configure it, the agent configuration will automatically show the updated name the next time you open it.
Popup-based OneDrive auth — Authenticating with OneDrive when browsing for folders/files now uses a popup window instead of redirecting you away from the page.
How to configure it
Step 1 — Open your agent's tool settings
In the Workshop, open the agent you want to configure. Navigate to its Tools settings and find the Microsoft 365 tool.
Step 2 — Enable the OneDrive toolkit
Make sure the Microsoft 365 toolkit is enabled for the agent. The folder/file scope picker only appears when Microsoft 365 is active.
Step 3 — Set the scope
Under "Limit OneDrive access to specific folders or files":
Click Browse to open the OneDrive file picker. If you haven't authenticated yet, a popup window will ask you to sign in with your Microsoft account.
Navigate to the folder or file you want to allow.
Click a folder name to open it and browse deeper.
Click the select button next to any folder or file to add it to the scope.
Repeat to add multiple folders and/or files.
Click Save when done.
Leave this section empty if you want the agent to have access to all of OneDrive. Scoping is opt-in — unconfigured agents have full access.
How scoping works
Once saved, the agent enforces these restrictions automatically at runtime:
What you scoped | What the agent can do |
A folder | Browse and read any file inside that folder (and subfolders) |
A specific file | Read only that file — it cannot browse or access anything else |
A folder + a file | Access files inside the folder and the specific pinned file |
The agent is aware of its restrictions. Its OneDrive tools are annotated with explicit instructions listing the permitted folder IDs and file IDs. Attempts to access anything outside the scope are blocked before they reach OneDrive.
Auto-refresh of names
When you reopen an agent's tool configuration, Hatz automatically fetches the current name and path of every scoped folder and file from OneDrive. If something was renamed since you last configured it:
The display name updates automatically in the config panel.
The underlying ID stays the same (OneDrive IDs are stable across renames), so the scope keeps working without any action needed.
If a scoped item was deleted from OneDrive, it silently stays in the list (with its last known name) until you manually remove it.
Use cases
Customer-facing agents with read access to shared folders Scope an agent to the specific OneDrive folder where your team stores contracts, SOPs, or product docs. The agent reads only from there, even if connected to a Microsoft 365 account with broader access.
Single-document workflows Pin an agent to a specific spreadsheet or report file. The agent can read and process that file but cannot explore anything else in OneDrive — useful for sensitive financials or HR documents.
MSP multi-tenant setups Configure separate agents per client with per-client OneDrive folder scopes, all under a single Microsoft 365 integration.
Dos and don'ts
Do
Use folder scoping when you want the agent to access a changing set of files over time (documents added to the folder are automatically accessible).
Use file scoping when you want to lock the agent to a single document regardless of what else is in the folder.
Re-open and review the scope config after renaming items in OneDrive — names will auto-update, but it's good practice to confirm.
Don't
Don't scope to a root-level folder with thousands of files if the agent only needs a subfolder — scope as tightly as possible for best performance and security.
Don't delete a scoped item from OneDrive without removing it from the agent config. The scope entry becomes inert (the agent can't access the deleted item), but it stays in the list until manually cleaned up.
Troubleshooting
The folder/file picker isn't showing up Make sure the OneDrive toolkit is checked in the agent's tool settings. The scope picker only appears when OneDrive is enabled.
The OneDrive popup is blocked Your browser may be blocking popups. Allow popups for your Hatz domain, then try again. Do not click the button multiple times — only one popup can be active at a time.
"Access denied" when the agent tries to read a file The file is outside the configured scope. Either add the file (or its parent folder) to the scope, or remove the scope restriction entirely if full access is intended.
A scoped folder is showing a stale name Close and reopen the tool config panel — names are refreshed from OneDrive on mount. If the name still doesn't update, the item may have been deleted or moved out of your account's accessible drives.
The agent can't find a file I pinned directly Check that the file still exists in OneDrive and hasn't been moved. If it was moved, the ID may have changed — remove it from scope and re-add it by browsing to its new location.