Choose the resources your Agent can use
Use file/folder scope to select the resources an Agent can use. Combine it with the Microsoft account’s permissions and selected tools to control the actions available on those resources. For read-only work, configure read permissions as well as the resource scope.
This feature lets you restrict an agent's OneDrive access to a specific set of folders or individual files. Choose the OneDrive folders or individual files the Agent can access.
Quick answer: edit the agent, open Tools, enable Microsoft 365, then use Browse under Limit OneDrive access to specific folders or files to add the allowed folder or file. Leave the scope empty only when the agent should use all OneDrive content available to the connected Microsoft account.
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, so unconfigured agents can use OneDrive content available to the connected Microsoft account.
How scoping works
Once saved, the agent enforces these restrictions automatically at runtime:
A folder scope restricts the supported operations to items within the allowed folder tree. A file scope identifies specific permitted files. This is a resource boundary, not a read-only mode: supported writes can also be checked against the source item and destination folder. Some actions cannot be used with a scope because their resources cannot be checked against it.
The Agent uses its saved scope when it runs. To add a resource for a new task, review the intended action and add the specific file or folder the Agent needs.
Auto-refresh of names
When you reopen an agent's tool configuration, Hatz checks 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 scope should continue to work across normal renames.
If a scoped item was deleted from OneDrive, remove it from the agent config and add a current folder or file if needed.
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 with verified SMB-client-specific connections and access settings. Folder scope does not by itself establish permission to access another client’s data.
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 Check the connected Microsoft account, provider permission, requested source or destination, and configured scope. Some actions cannot be checked against a file/folder scope and are refused. Keep the exact error for Support; do not assume every denial means the file is outside scope.
A scoped folder is showing a stale name Close and reopen the tool config panel. 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.


