Summary

Consolidate all remaining legacy-named tools into the consistent CQRS pattern (browse_* / manage_*), improve tool descriptions for AI agent discoverability, reorganize categories, and add missing manage actions.

CRITICAL: This issue describes the FINAL STATE after completion — not intermediate steps. All documentation references (prompts, guides, llms.txt, tool pages) must use the new names and categories.

Depends On

• docs: Prompt Library and advanced site features (Phase 2) #125 (Docs Phase 2 — Prompt Library, Guides, llms.txt)
• docs: Setup Wizard documentation and CLI reference (Phase 3) #130 (Docs Phase 3 — CLI docs, client docs, deployment docs)

Why blocked by docs: Documentation phases will create 30+ pages referencing current tool names. This issue must execute AFTER those pages exist, updating them in one pass to final names. Otherwise we'd create docs with legacy names and immediately rewrite them.

Current State: 8 Non-CQRS Tools

Duplicates (2 tools to DELETE)

Tier safety note: manage_ref displays as tier: Premium* (mixed), but its per-action gating already declares create_branch: { tier: "free", minVersion: "8.0" }. Deleting the standalone create_branch tool is safe — Free-tier users retain access via manage_ref action. Same for list_project_members — browse_members is tier: Free.

Renames (6 tools)

Already Consolidated (no action needed)

Final Tool Inventory (after consolidation)

Browse-Only Tools (5 tools)

Full CQRS Pairs (18 entities = 38 tools)

Special Tools (1)

Total: 44 tools (down from 47)

• Deleted: 3 tools (create_branch, list_project_members, download_attachment absorbed into browse_files)
• Renamed: 5 tools (net zero change)
• Net: 47 - 3 = 44

Implementation Plan

Phase 1: Delete Duplicates (breaking change)

1. Remove create_branch from registry
2. Remove list_project_members from registry
3. Remove associated schemas and handlers
4. Update tests that reference deleted tools

Phase 2: Renames (breaking change)

For each rename:

1. Create new schema file (or extend existing)
2. Create new handler (or extend existing)
3. Register new tool in registry
4. Remove old tool registration
5. Update unit tests
6. Update integration tests

get_users -> browse_users

const BrowseUsersSchema = z.discriminatedUnion("action", [
  z.object({
    action: z.literal("search").describe("Search users by name, username, or email"),
    query: z.string().describe("Search query (name, username, or email)"),
    per_page: paginationFields().per_page,
    page: paginationFields().page,
  }),
  z.object({
    action: z.literal("get").describe("Get single user by ID"),
    user_id: z.string().describe("User ID"),
  }),
]);

list_todos -> browse_todos

const BrowseTodosSchema = z.discriminatedUnion("action", [
  z.object({
    action: z.literal("list").describe("List todos with filtering"),
    state: z.enum(["pending", "done"]).optional(),
    action_type: z.enum(["assigned", "mentioned", "review_requested", ...]).optional(),
    type: z.enum(["Issue", "MergeRequest", "Epic", ...]).optional(),
    project_id: z.number().optional(),
    per_page: ..., page: ...,
  }),
]);

list_group_iterations -> browse_iterations

const BrowseIterationsSchema = z.discriminatedUnion("action", [
  z.object({
    action: z.literal("list").describe("List iterations for a group"),
    group_id: z.string().describe("Group ID or path"),
    state: z.enum(["opened", "upcoming", "current", "closed", "all"]).optional(),
    search: z.string().optional(),
    include_ancestors: z.boolean().optional(),
    per_page: ..., page: ...,
  }),
  z.object({
    action: z.literal("get").describe("Get single iteration details"),
    group_id: z.string().describe("Group ID or path"),
    iteration_id: z.string().describe("Iteration ID"),
  }),
]);

create_group -> manage_namespace

const ManageNamespaceSchema = z.discriminatedUnion("action", [
  z.object({
    action: z.literal("create").describe("Create a new group or subgroup"),
    name: z.string().describe("Group display name"),
    path: z.string().describe("URL-friendly path"),
    visibility: z.enum(["private", "internal", "public"]).describe("Group visibility level"),
    description: z.string().optional().describe("Group description"),
    parent_id: z.number().optional().describe("Parent group ID (creates subgroup when provided)"),
  }),
  z.object({
    action: z.literal("update").describe("Update group settings"),
    group_id: z.string().describe("Group ID or path"),
    name: z.string().optional().describe("New display name"),
    path: z.string().optional().describe("New URL path"),
    description: z.string().optional(),
    visibility: z.enum(["private", "internal", "public"]).optional(),
  }),
  z.object({
    action: z.literal("delete").describe("Permanently delete a group and all its projects"),
    group_id: z.string().describe("Group ID or path"),
  }),
]);

Design note: Single create action with optional parent_id instead of separate create_group/create_subgroup actions. The parent_id presence determines whether a top-level group or subgroup is created.

manage_repository -> manage_project

const ManageProjectSchema = z.discriminatedUnion("action", [
  z.object({
    action: z.literal("create").describe("Create a new project"),
    name: z.string().describe("Project name"),
    namespace: z.string().optional().describe("Group/namespace to create project in"),
    visibility: z.enum(["private", "internal", "public"]).optional(),
    description: z.string().optional(),
    initialize_with_readme: z.boolean().optional(),
  }),
  z.object({
    action: z.literal("fork").describe("Fork an existing project"),
    project_id: z.string().describe("Source project to fork"),
    namespace: z.string().optional().describe("Target namespace for fork"),
    name: z.string().optional().describe("Custom name for forked project"),
  }),
  z.object({
    action: z.literal("update").describe("Update project settings"),
    project_id: z.string().describe("Project ID or path"),
    name: z.string().optional(),
    description: z.string().optional(),
    visibility: z.enum(["private", "internal", "public"]).optional(),
    default_branch: z.string().optional(),
  }),
  z.object({
    action: z.literal("delete").describe("Permanently delete a project"),
    project_id: z.string().describe("Project ID or path"),
  }),
  z.object({
    action: z.literal("archive").describe("Archive a project (read-only, hidden from lists)"),
    project_id: z.string().describe("Project ID or path"),
  }),
  z.object({
    action: z.literal("unarchive").describe("Unarchive a project (restore to active state)"),
    project_id: z.string().describe("Project ID or path"),
  }),
  z.object({
    action: z.literal("transfer").describe("Transfer project to a different namespace"),
    project_id: z.string().describe("Project ID or path"),
    namespace: z.string().describe("Target namespace (group path or user)"),
  }),
]);

download_attachment -> browse_files action download_attachment

Add to existing BrowseFilesSchema discriminated union:

z.object({
  action: z.literal("download_attachment").describe("Download file attachment from issues/MRs"),
  project_id: z.string(),
  secret: z.string().describe("Security token from attachment URL"),
  filename: z.string().describe("Original filename"),
})

Phase 3: Tool Descriptions Rewrite (non-breaking)

Rewrite ALL tool descriptions to follow intent-first format with cross-entity disambiguation. Agent's decision tree: first sentence answers "WHEN should I use this?", then actions list, then disambiguation hints.

Description Format

[Intent sentence - when/why to use this tool]. Actions: [action list].
[Cross-reference to related tools if disambiguation needed].

New Descriptions (all 44 tools)

Projects & Repository:

Collaboration:

Planning:

CI/CD:

Integrations & Content:

Discovery:

Session:

Phase 4: Category Refactoring (non-breaking)

Reorganize tool categories for better AI agent discoverability. Currently 13 categories + "Other" dumping ground. New structure groups tools by intent.

Current Categories → New Categories

New Category Structure (7 categories)

Projects & Repository (11 tools)
├── browse_projects, manage_project
├── browse_namespaces, manage_namespace
├── browse_commits
├── browse_refs, manage_ref
├── browse_files, manage_files
└── browse_releases, manage_release

Collaboration (9 tools)
├── browse_merge_requests, manage_merge_request
├── browse_mr_discussions, manage_mr_discussion, manage_draft_notes
├── browse_members, manage_member
└── browse_todos, manage_todos

Planning (7 tools)
├── browse_work_items, manage_work_item
├── browse_milestones, manage_milestone
├── browse_iterations
└── browse_labels, manage_label

CI/CD (5 tools)
├── browse_pipelines, manage_pipeline, manage_pipeline_job
└── browse_variables, manage_variable

Integrations & Content (8 tools)
├── browse_webhooks, manage_webhook
├── browse_integrations, manage_integration
├── browse_wiki, manage_wiki
└── browse_snippets, manage_snippet

Discovery (3 tools)
├── browse_search
├── browse_events
└── browse_users

Session (1 tool)
└── manage_context

Total: 44 tools across 7 categories (vs current 14 categories with "Other")

Files to Update for Category Refactoring

Phase 5: New manage_project and manage_namespace Actions (minor)

Currently manage_repository only has create and fork. After rename to manage_project, add missing CRUD actions.

manage_project — New Actions

manage_namespace — New Actions

Tier Gating for New Actions

Add to ToolAvailability.actionRequirements:

manage_project: {
  default: { tier: "free", minVersion: "8.0" },
  actions: {
    create: { tier: "free", minVersion: "8.0" },
    fork: { tier: "free", minVersion: "8.0" },
    update: { tier: "free", minVersion: "8.0" },
    delete: { tier: "free", minVersion: "8.0" },
    archive: { tier: "free", minVersion: "8.0" },
    unarchive: { tier: "free", minVersion: "12.4" },
    transfer: { tier: "free", minVersion: "11.1" },
  },
},
manage_namespace: {
  default: { tier: "free", minVersion: "8.0" },
  actions: {
    create: { tier: "free", minVersion: "8.0" },
    update: { tier: "free", minVersion: "8.0" },
    delete: { tier: "free", minVersion: "8.0" },
  },
},

Documentation Updates (CRITICAL — execute AFTER #125 and #130)

After docs phases are complete, the following files will reference legacy tool names and MUST be updated:

Auto-generated (no manual action needed)

Manual updates required

Note: docs/public/llms.txt is a manually-maintained static file. There is no --export-llms CLI flag. The documentation URL is https://gitlab-mcp.sw.foundation/.

Specific renames in docs (grep and replace)

Category-related updates

VitePress navigation updates

Semver Impact

MAJOR version bump — this is a breaking change:

• 2 tools removed (agents using create_branch/list_project_members will break)
• 6 tools renamed (agents using old names will break)
• 1 tool absorbed (agents using download_attachment will break)
• New actions added to existing tools (non-breaking, additive)
• Description changes (non-breaking, cosmetic)
• Category changes (non-breaking, cosmetic)

Consider adding deprecation warnings for 1 release before removal:

// Option: emit warning in response for 1 version, then remove
{ warning: "Tool 'create_branch' is deprecated. Use manage_ref with action 'create_branch'." }

Tests

Unit Tests

• Remove tests for deleted tools
• Create tests for all new/renamed schemas
• Verify discriminated unions parse correctly
• Verify read-only mode respects new names
• Test new manage_project actions (update, delete, archive, unarchive, transfer)
• Test new manage_namespace actions (update, delete)
• Verify category assignment in list-tools output

Integration Tests

• Verify browse_users search works (was get_users)
• Verify browse_todos list works (was list_todos)
• Verify browse_iterations list/get works
• Verify manage_namespace create/update/delete works
• Verify manage_project create/fork/update/delete/archive/unarchive/transfer works
• Verify browse_files download_attachment action works

Regression Tests

• Ensure manage_ref action create_branch still works after deleting standalone tool
• Ensure browse_members action list_project still works after deleting standalone tool

Acceptance Criteria

• Zero legacy-named tools remain (get_*, list_*, create_*, download_*)
• All 44 tools follow browse_* / manage_* / manage_context pattern
• All tool descriptions follow intent-first format with cross-references
• Categories reorganized (7 intent-based vs 14 with "Other" dump)
• manage_project supports: create, fork, update, delete, archive, unarchive, transfer
• manage_namespace supports: create, update, delete
• All docs pages use new tool names (zero grep hits for old names)
• docs/TOOLS.md will auto-regenerate on next release (semantic-release)
• docs/public/llms.txt manually updated with new tool names (static file, no CLI generation)
• All unit tests pass
• All integration tests pass
• CHANGELOG clearly lists breaking changes with migration guide

Deferred (out of scope)

• Action naming standardization (tree→list_tree, user→list_user, etc.) — breaking change with high effort/low impact ratio. Defer to future issue.
• download_attachment semantic mismatch — keeping in browse_files with disambiguation in description. Revisit if agents consistently fail to find it.