Implement tool consolidation and categorization for tool routing

Proposal

In !201838 (merged) we implemented an annotation-style approach (framework) that allows 1:1 mapping between tools and API endpoints.

While we may still want granular tools in some cases, we should also explore possibilities to extend the existing framework approach to support consolidation of tools as we expect to run into quality issues as the number of implemented tools continues to grow- for more details see https://gitlab.com/gitlab-org/gitlab/-/issues/562157#note_2700443469. Tool consolidation could furthermore help in reducing costs since we include all available tools in the context when communicating with agentic chat.

Terminology

• Granular tool: A simple tool that maps directly to an API endpoint. The main use case will be the flow registry where users can pick specific and different tools they want to use. For example, they can add a fetch_issue tool and not allow fetch_mr
• Complex tool: A complex tool does necessarily map to a single API endpoint. Instead, it could combine functionality from various endpoints and expose it behind a single tool. Use cases are AI chats and normal MCP clients where users don’t really care about specific tools and their settings; they just expect to “chat with GitLab”. It’s more of an optimization to reduce the number of tokens and improve result quality. For example, fetch_gitlab_resource can fetch issues, MRs, and epics with one tool definition. We use tool consolidation when designing complex tools.
• Tool routing: Refers to the mechanism by which the server determines which specific tool (or subset of tools) should handle an incoming request from a client.