## 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 the concept of a deprecated tool. `unlisted` already exists and covers part of this, but it is not the same concept — it was added so a tool could be registered without being turned on for consumption yet, for example behind a feature flag. Deprecation is the other end of a tool's life and has to account for references that already exist. A deprecated tool must: - continue to be accepted and allowlisted everywhere it is accepted today - still be returned by `tools/list` for catalog consumers - never be returned by `tools/list` for non-catalog consumers - not be addable to new or existing AI Catalog agents. An agent that already has one can view, remove or replace it - surface a warning where an agent references it - report usage through Kibana and from SM instances, so we can see who is still calling it before removal **The flag has to reach both namespaces.** A tool can be referenced two ways, and they do not share a mechanism: | | MCP tool | Built-in catalog tool | |---|---|---| | Referenced as | `def_mcp_tools: ["get_issue"]` | `def_tools: [17]` | | Defined in | `Mcp::Tools::*Service` classes | `ee/lib/ai/catalog/built_in_tool_definitions.rb` | | Carries a flag | `unlisted?`, overridable per class | none — `Ai::Catalog::BuiltInTool` is a `FixedItemsModel` with only `id, name, title, description` | Hiding a built-in from the AI Catalog picker has only ever been done by hardcoding its integer id in `ee/app/graphql/ee/types/query_type.rb` (`tools.reject! { |t| t.id == 58 }`, plus 78 and 79 behind a feature flag). A `deprecated` flag that only lands on the MCP side leaves the built-in entry selectable. ### What `unlisted` covers in the meantime #622712 is shipping the consolidation with `unlisted` for %19.5, on the basis that the priority for MCP GA is the server surface itself and `deprecated` can follow. Measured against the prerequisites above, `unlisted` gives us: | Prerequisite | `unlisted` | |---|---| | Still allowlisted everywhere | yes — stays in `PRIVILEGE_GROUP_MAPPING` and `rulable_tool_names`, and existing `Ai::ToolRule` rows stay valid | | Returned to catalog consumers | yes — stays in `Ai::Catalog::McpTool.fixed_items`, so `find_by_name` resolves and stored agents render | | Not returned to other consumers | yes — filtered in `lib/api/mcp/handlers/list_tools.rb` | | Not addable to new agents | **partly** — filtered from `ai_catalog_mcp_tools`, but a built-in twin stays selectable | | Warning on affected agents | no | | Usage reporting | no | Tools already unlisted that still have a built-in twin, so are still offered when building a new agent: `create_issue` (id 6) and `get_issue` (id 17). ### 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. `ai_tool_rules` has a `tool_arguments` jsonb column, added with the table but not read anywhere today — only the validator references it. If argument-scoped rules are the intended answer here (`get_merge_request` allowed, `include: conflicts` denied), that column is the place for it, and the Governance team should confirm. This is not hypothetical. Alias resolution already rewrites 18 catalog names, several of them writes: `create_commit` resolves to `add_commit`, and five vulnerability tools resolve to `save_vulnerability`. An agent configured only to dismiss a vulnerability receives the broader `save_vulnerability` tool. Raised by `@jessieay` on !256871. - How should a migration handle prompt text? Tool names appear in agents' `system_prompt` and `user_prompt`, which a data migration over a tools array cannot reach. -