The Hook
Every redundant byte returned by an MCP tool is tokenized directly into the LLM's context window—meaning an unoptimized GraphQL selection set on list_merge_requests doesn't just slow down PostgreSQL; it burns tens of thousands of tokens per agent turn and crowds out reasoning capacity.
The Deep Dive
When building MR !270521 (feat(mcp): add merge request read fields and reviewer filter) to close Issue #639870, our goal was to give AI agents rich code-review awareness in list_merge_requests and get_merge_request—adding reviewers, labels, draft, createdAt, updatedAt, diffHeadSha, detailedMergeStatus, and a new reviewer_wildcard_id (NONE or ANY) filter for triaging unassigned queues. However, naively expanding the GraphQL query and REST response payload on high-traffic repositories like gitlab-org/gitlab immediately surfaced three architectural constraints: parameter conflict semantics, database N+1 query amplification, and LLM context-window bloat.
First, in GitLab's GraphQL API, passing reviewerWildcardId alongside reviewerUsername or scope: review_requested triggers a GraphQL execution error, which the MCP layer would log as a generic tool_status: error (5xx-equivalent server fault) instead of a client validation mistake. In MR !270521, I added pre-query mutual-exclusion validation in ListMergeRequestsService that rejects conflicting filter combinations upfront as Mcp::Tools::Response.error (tool_status: bad_request), and registered reviewer_wildcard_id in ee/spec/lib/ai/tool_rules/governable_tools_container_spec.rb. Second, exposing reviewers and labels across 100 merge requests risked triggering N+1 database queries across merge_request_reviewers and label_links; we verified batch preloading in both CE (FOSS_ONLY=1) and EE RSpec suites using ActiveRecord::QueryRecorder without mutating frozen let_it_be test fixtures.
Third—and most critically for AI agent ergonomics—we measured the real-world payload impact against 100 merge requests on gitlab-org/gitlab. Returning full label objects (id, title, color, description) ballooned a 100-MR response from 80 KB to 132 KB. By keeping minimal GraphQL node selections (nodes { title }) to satisfy @graphql-eslint/require-selections and transforming labels into a flat array of title strings in format_merge_request, we preserved every piece of triage signal the LLM needs while cutting the payload back to 80 KB—saving ~40% (~52 KB / ~13,000 tokens) per tool call.
The GitLab Hero Angle
GitLab's MCP server tools (MR !270521) are engineered specifically for LLM token economics and PostgreSQL efficiency—combining batch-loaded GraphQL resolvers with compact post-processed projections so GitLab Duo agents can triage 100+ merge requests in a single turn without blowing context limits.
The Takeaway
Treat MCP tool response schemas as LLM context-budget contracts: select the minimal GraphQL fields required, flatten verbose join metadata into scalar arrays before returning to the agent, and enforce QueryRecorder N+1 bounds in CI.
Top comments (0)