UX Proposal: DAP Tool Permissions
Background
Tools are the discrete capabilities that agents and flows use to take action in GitLab — things like get_issue, create_comment, or close_issue. Today, any enabled agent or flow may invoke any available tool, subject only to the triggering user's GitLab permissions. There is no mechanism for group owners or administrators to restrict which tools agents and flows are permitted to use in their environment.
GitLab Duo Agent Platform currently has a few dozen tools, with plans to expand to hundreds as the platform matures. As this catalog grows — and as enterprises adopt DAP for increasingly sensitive workflows — the ability to govern which tools are available becomes a prerequisite for confident adoption, particularly in regulated industries.
This proposal describes a Tool Permissions setting in the GitLab Duo configuration page that allows group owners (on GitLab.com) and instance administrators (on self-managed GitLab) to define a platform-wide policy for how each tool may be used by any agent or flow.
Problem
Without tool-level permission controls, administrators have no way to:
- Prevent agents or flows from using destructive tools (e.g. delete operations) that weren't anticipated when the agent or flow was created.
- Require explicit user confirmation before sensitive write actions are taken on behalf of a user.
- Communicate organizational policy around AI-initiated actions to their security or compliance teams.
This gap is a meaningful barrier to enterprise adoption of DAP, particularly for organizations that require human oversight of AI-initiated write and delete operations.
Proposal
Gitlab Tool Permissions
Add a Gitlab Tool Permissions section to the existing GitLab Duo configuration page. This section allows administrators to set a permission policy for all tools available in the platform, organized into three categories: Read-only, Write, and Delete.
Each category — and each individual tool within it — can be set to one of three states:
- Always allow — The tool may be used by any agent or flow without prompting the triggering user.
- Always ask — Before the tool is used, the triggering user must explicitly approve it. For flows, this surfaces in the pre-execution approval modal described in #591223 (closed). For agents in Duo Chat, this continues the existing inline tool-approval UI pattern already present in Chat.
- Blocked — The tool is unavailable to all agents and flows in this group or instance. If a flow or agent attempts to invoke a blocked tool, it is noted in the session log as unavailable; execution continues for any remaining steps.
These settings apply to all agents and flows in the group or instance — including the main GitLab Duo agent used in Agentic Chat, and all foundational agents and flows shipped and maintained by GitLab (e.g. Duo Planner, Developer Flow, Fix CI/CD Pipeline Flow). They represent the administrative ceiling — individual users may further restrict tools at execution time (per #591223 (closed)), but cannot elevate beyond what the admin has permitted.
Administrators should be aware that these settings are intentionally powerful. It is possible to configure Tool Permissions in ways that render specific agents or flows partially or entirely non-functional — for example, blocking every tool would prevent all agents and flows from taking any action. Similarly, marking every tool as Always ask would introduce a confirmation prompt for every tool invocation, significantly increasing friction for all users. GitLab will surface warnings when changes are likely to impact existing agents and flows, and will provide defaults that reflect a reasonable balance between security and usability. Ultimately, each organization is responsible for determining the right policy for their context.
Each tool name is linked to a corresponding entry in the Duo documentation. e.g. Clicking on get_issue should link to something like: https://docs.gitlab.com/api/issues/
External Tool Permissions
A second section, External Tool Permissions, appears below GitLab Tool Permissions on the same configuration page. It controls which tools any GitLab agent or flow may use in external systems through connected MCP servers.
Each connected MCP server appears as a collapsible row, showing the server name, a count of its tools, and a dropdown for setting a server-level policy. The dropdown options are the same as GitLab Tool Permissions: Always allow, Always ask, and Blocked.
Expanding a server reveals a flat list of its tools. Each tool displays its name, a count of agents and flows within this group currently using it, and a segmented button control (✓ Always allow /
Default state for new MCP servers
When a new MCP server is connected, its default policy is Always ask for all tools. This conservative default reflects the fact that GitLab cannot verify the behavior or risk level of external tools. Admins may adjust this after reviewing the server's tool list.
Known limitations based on assumptions
The MCP specification does not include a standard mechanism for categorizing tools. It is assumed that GitLab cannot reliably infer whether an external tool is read-only, destructive, or otherwise sensitive based on its name or description alone. For this reason, External Tool Permissions does not attempt to group MCP tools by category — tools are presented as a flat list within each server, and admins are responsible for reviewing individual tools before adjusting permissions.
For groups with MCP servers that expose a large number of tools, the expanded tool list may become difficult to navigate. A searchable, filterable tool list within each server is a future consideration once the scale of real-world MCP server usage is better understood.
UX Screens
1. Placement
Gitlab Tools Settings and External Tool Settings sections are added to the Configuration page within Group / Settings / GitLab Duo.
2. Gitlab Tool Permissions - Default state
3. Gitlab Tool Permissions - Dropdown
4. Gitlab Tool Permissions - Expanded - all set to Allow All
5. Gitlab Tool Permissions - Expanded - Mixed tool permissions and warning
6. External Tool Permissions - Expanded
Note that the tool name is not linked to any description, since we won't know where the description is for each MCP's tool.
UI Behavior
Collapsed state (default)
The Tool Permissions section displays three collapsible rows — Read-only tools, Write tools, and Delete tools — each showing a count of the tools in that category and a dropdown reflecting the current category-level policy.
Category-level batch control
The dropdown for each category applies a single permission state to all tools within it at once. Available values are Always allow, Always ask, and Blocked. This covers the majority of admin configurations without requiring per-tool decisions.
When the tools within a category do not all share the same state, the dropdown displays Custom. This is a read-only display state — it cannot be selected directly. It appears automatically when individual tool overrides cause the category to have mixed permission levels.
Expanded state
Expanding a category reveals each individual tool with its own permission control: a segmented button group showing the three states (checkmark = Always allow, warning triangle = Always ask, blocked circle = Blocked), with the active state highlighted.
Impact warning
When an admin changes a tool from its current state to a more restrictive one (Always ask or Blocked), and one or more agents or flows within the group currently use that tool, a warning is shown inline beneath that tool before the admin saves:
⚠️ This change will impact [N] agents and flows in this group.
This warning is informational and does not block the save action. It is scoped to agents and flows enabled within the current group only.
The "[N] agents and flows" text is intended to link to a filtered view of the AI Catalog showing all agents and flows that use this specific tool and are currently enabled for the group — giving admins a way to understand the blast radius before committing. This is a future consideration, pending the availability of filterable, per-tool views in the AI Catalog.
Save behavior
Tool permission changes are not applied until the admin clicks Save changes at the bottom of the GitLab Duo configuration page, consistent with the existing save behavior on that page.
Default states
The proposed defaults balance usability with a reasonable safety posture for new adopters:
| Category | Default |
|---|---|
| Read-only tools | Always allow |
| Write tools | Always ask |
| Delete tools | Blocked |
These defaults are intentionally conservative for write and delete operations, reflecting the elevated risk of AI-initiated mutations and destructive actions. Admins may adjust any category or individual tool to fit their organization's needs.
Relationship to #591223 (closed) (Flow Action Approvals)
These two features operate at different layers of the same permission model:
- This proposal (admin layer): Sets the organizational policy ceiling. Determines which tools are available at all, and which categories require user confirmation by default.
- #591223 (closed) (user layer): Gives the triggering user a per-session opportunity to review and further restrict tools before a flow runs.
When an admin marks a tool as Always ask, the user will always encounter an approval prompt for that tool — either in the pre-execution modal (flows) or inline in Chat (agents) — regardless of what the flow author configured.
When an admin marks a tool as Blocked, it is removed from consideration entirely and cannot be re-enabled by the user at execution time.
Design notes
- "Custom" is not actionable. Admins cannot select Custom; they can only create that state by adjusting individual tools. See Future Considerations for a proposed recovery affordance.
- Tool list will grow significantly. The UI must scale gracefully from ~30 tools today to hundreds. The collapsed-by-default category view is essential for this; per-tool configuration should remain an opt-in expansion for power users and edge cases. -Current Categorization of Read, Write and Delete has been informed by user research, but we expect these categories may need to change with user feedback. Given that permissions are ultimately set per-tool, this pattern should be adaptable to future categorizations.
- Blocked tools and flow authors. Flow and agent authors are not currently notified when a tool they depend on is blocked by an admin. A future improvement could surface blocked-tool conflicts in the AI Catalog when an agent or flow is viewed, or at the time a new agent/flow is enabled for a group.
Future considerations
Linked impact view. The impact warning currently shows a count of affected agents and flows. Once the AI Catalog supports filtering by tool, this count should become a link that opens a filtered Catalog view scoped to the current group — giving admins direct visibility into what they're affecting before saving.
Tool sub-categories. The current taxonomy of Read-only, Write, and Delete works well at the current scale of ~30 tools. As the tool catalog expands into the hundreds, this flat structure will become difficult to manage. At that point, functional sub-categories — such as groupings by domain (Issues, Merge Requests, CI/CD, Security) — should be introduced within or alongside the existing permission-level groupings. This would allow admins to make scoped policy decisions (e.g. allowing all issue tools but blocking all CI/CD tools) without reviewing hundreds of individual entries.
"Custom" recovery affordance. When a category is in the Custom state, there is no direct way to reset all tools in that category back to a uniform policy without clicking each one individually. Future expansions on this could involve saving configurations as policies unique for each top level group, and being able to revert to that policy quickly if changes are made.