## Description We need a backwards compatible way to allow MCP tool consumers to update stored tool names as MCP tools are deprecated, renamed, or removed. MCP tools can be allowlisted/stored in multiple places in the codebase. An exhaustive sweep of the monorepo (Ruby, Go) and the ai-assist repo identified the following storage locations: ### Tool-name storage locations | # | Location | Construct | Form | |---|---|---|---| | 1 | `ee/lib/ai/foundational_chat_agents_definitions.rb` | `tools:` in defs; `BuiltInTool.where(name: tools.map(&:to_s))` | symbols → strings | | 2 | `ee/lib/ai/catalog/built_in_tool_definitions.rb` | `ITEMS` (93 tools, stable hardcoded int ids) | int id + string name | | 3 | `ee/app/models/ai/catalog/item_version.rb` → `ai_catalog_item_versions.definition` jsonb | `tools`, `mcp_tools`, `system_prompt`, `user_prompt` | int ids + strings | | 4 | `app/validators/json_schemas/ai_catalog/agent_v1.json` | `tools` (int array), `mcp_tools` (string array, maxItems 100), `mcp_servers` (int array) | ints + strings | | 5 | `app/validators/json_schemas/ai_catalog/flow_v2.json` | `toolset` arrays + `tool_name`; objects keyed by name | strings embedded in flow def | | 6 | `app/services/mcp/tools/manager.rb` (+ EE) | `CUSTOM_TOOLS`, `GRAPHQL_TOOLS`, `alias_map`, `route_setting :mcp` | canonical strings | | 7 | `base_service.rb` / `api_tool.rb` | `tool_aliases`, `unlisted?` | strings / boolean | | 8 | `ee/app/services/ai/duo_workflows/mcp_config_service.rb` | `mcp_tools_for_agent`; emits prefixed `gitlab_<tool>` / `orbit_<tool>`; `ORBIT_PREAPPROVED_TOOLS` | strings + prefixed | | 9 | `ee/lib/ai/tool_rules/registry.rb` | `PRIVILEGE_GROUP_MAPPING` (~120 names), `UNGOVERNED_TOOLS`, `MCP_TOOL_NAME_FOR` (catalog→MCP alias) | ~120 strings + alias map | | 10 | `ee/app/models/ai/tool_rule.rb` → table `ai_tool_rules` | `tool_name` (validated vs Registry), `tool_source`; unique `(namespace_id, project_id, tool_name)` | DB strings | | 11 | `ee/app/services/ai/tool_rules/resolution_service.rb` | group→privilege partitioning → `Registry.to_mcp_tool_names` | strings | | 12 | `duo_workflows_workflows.tool_call_approvals` jsonb | runtime per-workflow approvals keyed by tool name | DB, tool-name keys | | 13 | `ai_catalog_mcp_servers.name` | MCP server name (used for `<server>_` prefixing) | DB string (server, not tool) | | 14 | `ee/app/models/ai/catalog/mcp_tool.rb` | `fixed_items` snapshot from `Manager#list_tools` + orbit | strings | | 15 | `ee/lib/api/orbit/mcp_handlers/tool_catalog.rb` | `COMMAND_TOOL_NAMES = %w[list_commands invoke_command]` | strings (Orbit) | | 16 | `ee/app/models/ai/duo_workflows/workflow.rb` | `ToolCallApprovals` with `COMMAND_TOOL_NAME`, `GIT_COMMAND_TOOL_NAME` | strings | | 17 | `ee/lib/gitlab/llm/completions/chat.rb` + `chain/tools/*/executor.rb` | legacy Duo Chat `TOOLS`/`COMMAND_TOOLS` + per-tool `NAME` | PascalCase strings (separate namespace) | | 18 | int-id→name bridges: `agent_definition.rb`, `duo_workflow_payload_builder/v1.rb`, `v1_agent_definition_wrapper.rb` | `BuiltInTool.where(id:).map(&:name)` | ints → strings | | 19 | `workhorse/internal/api/api.go` | `McpServerConfig{ Tools *[]string, PreApprovedTools *[]string }` | Go `*[]string` | | 20 | `workhorse/internal/ai_assist/duoworkflow/mcp.go` | `gitlabServerName`/`orbitServerName`, prefixed `name+"_"+tool.Name`, filters on unprefixed name | prefixed `gitlab_`/`orbit_` strings | | 21 | `https://gitlab.com/gitlab-org/duo-ui/-/blob/main/src/components/chat/components/duo_chat_message/message_types/tool_message_registry.js?ref_type=heads` | | | ### ai-assist (external consumer) MCP tool names arrive dynamically as protobuf `McpTool` messages and travel as opaque strings — new/renamed tools flow through transparently in almost all paths. Three places hardcode GitLab MCP names and would break on rename: 1. `duo_workflow_service/workflows/chat/workflow.py` — `if "search" in enabled_mcp_tools` (de-dupes native vs MCP search) 2. `lib/context/orbit.py` — `ORBIT_TOOL_IDENTIFIER`/`_ORBIT_TOOL_NAME_PREFIX` for billing 3. `agent_platform/v1/flows/configs/orbit_agent/1.0.0.yml` — hardcoded Orbit tool names in `toolset:` ### Key observations - **Two distinct namespaces** that don't cross-resolve: (a) built-in tool integer ids, (b) string names. Legacy Duo Chat PascalCase `NAME`s are a third. - **`MCP_TOOL_NAME_FOR`** in `ToolRules::Registry` already contains a catalog→MCP rename (`create_issue` → `create_work_item`) — a precedent for renames outside `tool_aliases`. - **Two DB stores key on tool-name strings** and would orphan silently on rename: `ai_tool_rules.tool_name` and `duo_workflows_workflows.tool_call_approvals`. - **Silent-drop bug**: `McpConfigService#mcp_tools_for_agent` intersects agent tool names against `manager.list_tools.keys` (canonical names only, aliases excluded). A stored name that becomes an alias is dropped with no log entry. ## Proposal MCP tools can be migrated following this process over multiple merge requests. ### Pre-requisites Introduce concept of deprecated/unlisted tools. - Deprecated tools must continue to be accepted and allowlisted in any place they currently are today. - Deprecated tools must come back on a `tools/list` call for catalog consumers. - Deprecated tools must never be served on a `tools/list` call for non-catalog consumers. - Deprecated tools are not allowed to be added in new or existing AI Catalog agents. If an agent has them already allowlisted, they can only be viewed/removed/replaced. - Users should see an alert/warning some UX notification when their AI Catalog agents reference deprecated tools. - Use of deprecated tools should be reported through existing mechanisms in kibana and from SM instances so we can gauge the use. ### Milestone 1 * MR 1 - Introduce the new tool, mark any tools being replaced as deprecated/unlisted using mechanism above. * MR 2 - Move existing GitLab tools to the new tool name. This could be through a DB migration (targeted to GitLab managed tools only) or hardcoded file changes. ### Milestone M+? - next required stop * MR 3 - Mark database migration as finalized * MR 4 - Remove deprecated/unlisted tools from codebase - this would be a breaking change for agents that do not update. ## Questions - Will there any way to restrict what features of the new consolidated tools? For example, `get_merge_request` previously just fetched merge request data, but now will be more powerful. -