## Why &20222 consolidates the MCP catalog onto facet readers (`get_*` with `include`) and unified writers (`save_*`). Several of the consolidated replacements have now shipped, but the tools they supersede are still registered. Both generations being present is the exact problem the epic set out to fix: agents pick the narrower legacy tool, the catalog stays large, and every tool carries maintenance cost. This issue tracks retiring the superseded tools once each replacement is verified to fully cover them. ## Ready to deprecate Replacement already covers the full capability — deprecate and remove: | Remove | Superseded by | Status | | --- | --- | --- | | `get_merge_request_diffs` | `get_merge_request` + `include: ["diffs"]` (`detail: full_patch`) | **Unlisted** in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/255288; removal follow-up: https://gitlab.com/gitlab-org/gitlab/-/work_items/630281 | | `get_merge_request_commits` | `get_merge_request` + `include: ["commits"]` | **Unlisted** in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/255298 | | `get_merge_request_pipelines` | `get_merge_request` + `include: ["pipelines"]` | **Unlisted** in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/255298 | | `get_merge_request_conflicts` | `get_merge_request` + `include: ["conflicts"]` | **Unlisted** in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/257349; retire by alias MR closed: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/252513 (https://gitlab.com/gitlab-org/gitlab/-/work_items/628612) | | `get_pipeline_jobs` | `get_pipeline` + `include: ["jobs"]` (fewer job fields: no `failure_reason`, `duration`, `queued_duration`, or timestamps — accepted, see [discussion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/255288#note_3902525818)) | **Unlisted** in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/255288; removal follow-up: https://gitlab.com/gitlab-org/gitlab/-/work_items/630280 | | `create_merge_request_note` | `save_merge_request_review` + `method: create_note` / `reply_discussion` | **Done** — alias on `save_note` since https://gitlab.com/gitlab-org/gitlab/-/merge_requests/250829, so it was never listed | | `get_issue` | `get_work_item` | **Unlisted** in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/254571; removal follow-up: https://gitlab.com/gitlab-org/gitlab/-/work_items/629035 | ## Blocked on a capability gap Deprecate only after the linked issue closes the gap: | Remove | Superseded by | Blocked on | Status | | --- | --- | --- | --- | | `get_workitem_notes` | `get_work_item` + `include: ["notes"]` | Closed: https://gitlab.com/gitlab-org/gitlab/-/issues/622710 | **Unlisted** in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/254299; removal follow-up: https://gitlab.com/gitlab-org/gitlab/-/work_items/629004 | | `create_issue` | `save_work_item` (`type_name: "Issue"`) | Closed: https://gitlab.com/gitlab-org/gitlab/-/issues/622711 | **Unlisted** in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/254298; removal follow-up: https://gitlab.com/gitlab-org/gitlab/-/work_items/628856 | | `get_merge_request_notes` | `get_merge_request` + `include: ["notes"]` | Closed: https://gitlab.com/gitlab-org/gitlab/-/work_items/630555 (backward paging, `position`, and `discussion` fields added in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/258219) | **Unlisted** in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/256931 | ## Status All tools above are unlisted, and all unlist MRs are merged. Removal of each tool is tracked in its own follow-up issue, linked in the tables. `get_merge_request_commits`, `get_merge_request_pipelines`, `get_merge_request_conflicts`, and `get_merge_request_notes` don't have a removal follow-up yet. ## Explicitly not deprecated - `manage_pipeline` — narrow its scope to rename/delete rather than remove it. `save_pipeline` cannot rename or delete a pipeline (see #619469); only the create/retry/cancel and list paths are superseded, by `save_pipeline` and `list_pipelines`. - `semantic_code_search` — semantic retrieval over a different corpus than `search` with `scope: blobs`. Consolidation is tracked separately under &23244. - `search` (`work_items` / `merge_requests` scopes) — instance and group wide, whereas the `search` parameter on `list_work_items` / `list_merge_requests` is namespace scoped. Not duplicates. ## Proposed approach 1. Confirm per-tool parity against the replacement (parameters, response shape, pagination) before removing anything — the gap table above came from reading tool descriptions, so verify against the implementations. 2. Mark each ready tool as deprecated in its description first, pointing at the replacement and the `include` value or `method` to use, so agents migrate before removal. 3. Remove after one milestone of deprecation notice. 4. Update the [MCP server tools docs](https://docs.gitlab.com/user/model_context_protocol/mcp_server_tools/) — coordinate with #616834, which is already doing a bulk docs pass. ## Open question Whether any of these tools need a formal deprecation and removal announcement, or whether the MCP tool surface is still considered experimental enough to change in place. Worth confirming with product before the removal step. Related to &20222, &22782, &22781, &22783.