GraphQL Operation Descriptions: How a Spec Update Solved Our MCP Problem

The Cosmo MCP Gateway turns trusted GraphQL operations into MCP tools that AI agents can call. MCP tools need descriptions so LLMs can understand what each tool does. Without a standardized approach, teams had to choose between non-standard comments, custom directives, or separate configuration files. The September 2025 GraphQL spec update added official support for operation descriptions. Operations are now self-documenting, portable across all GraphQL tooling, and work with AI systems without custom infrastructure. Available in Cosmo Router v0.262.0.

When we built the MCP Gateway for Cosmo, we ran into a documentation problem.

The gateway takes trusted GraphQL operations (the queries and mutations you've approved or curated) and exposes them as MCP tools that AI agents can call. But MCP tools need descriptions. Without them, AI models have to guess what a tool does based on the operation name and schema documentation. While we can generate descriptions from JSON Schema and SDL documentation, that doesn't capture the purpose of the tool as efficiently as a human-written description.

We wrote an internal RFC to solve this. Customers wanted to describe their operations without modifying the GraphQL schema or maintaining separate JSON configuration files.

The obvious answer seemed simple: just add descriptions to the operations themselves.

But GraphQL didn't support that. At least, not officially.

The RFC evaluated three approaches. Each had trade-offs.

The first option was to parse comments:

Apollo does this. They have custom parsers that extract comments and treat them as documentation.

While Apollo's approach worked for their use case, it had limitations. Comments are part of the GraphQL spec grammar, but they're not included in the AST. They're stripped during parsing, which means they're not portable across tools. Different parsers handle them differently, and if you're building infrastructure that needs to be reliable and work across the ecosystem, this creates problems.

We didn't want to go down that path.

The second option was to introduce a custom directive:

This would be spec-compliant. Directives are part of GraphQL, and we could vendor-namespace it.

But it adds complexity. We'd need to parse this custom directive even if it wasn't in the SDL. Every tool in the ecosystem would need to understand it. It's not portable. And it felt like we were working around the problem rather than solving it properly.

The third option was to extend our GraphQL parser to support description strings on operations:

This syntax already existed for schema types. It's clean. It's consistent with how GraphQL documents everything else.

But there was a catch: operation descriptions weren't explicitly defined in the GraphQL spec.

They were a de facto standard (widely supported by tools like GraphQL Playground, Apollo Studio, and GraphiQL) but not officially part of the specification.

That made us nervous. We'd be implementing something that wasn't standardized, which could lead to compatibility issues down the line.

Operation descriptions became official.

Queries, mutations, subscriptions, and fragments can now have descriptions using the same triple-quoted string syntax as schema types:

That description is now part of the GraphQL document AST. It's standardized. It's portable. And it's exactly what we needed.

With official support for operation descriptions, the MCP Gateway can now read them directly from the GraphQL AST and expose them as tool descriptions.

When you define an operation like this:

The MCP Gateway automatically turns it into a tool:

No extra configuration. No custom parsing. No directives. Just standard GraphQL.

GraphQL schemas were self-describing, but operations weren't. You could introspect a schema to understand types, fields, and arguments. Operations required reading code. Now they're self-documenting.

• Operations are self-documenting, making it easier to build documented backend-for-frontends
• Documentation can't diverge from implementation
• Code reviews are clearer

• AI agents use operation descriptions for better tool selection
• Clear descriptions reduce model errors
• Operations are discoverable in AI workflows

• No custom parsers or metadata conventions needed
• Descriptions work consistently across all GraphQL tools
• Less custom code to maintain

The spec update also covers fragments:

This is particularly useful in federated graphs where fragments might span multiple subgraphs. When the MCP Gateway processes operations that include fragments with descriptions, it carries that context into tool metadata.

If multiple operations use UserFields, the fragment description provides consistent context across all of them.

Support for operation descriptions is available in Cosmo Router v0.262.0 and later.

To use it:

1. Add triple-quoted description strings to your operations
2. Upgrade to Cosmo Router v0.262.0 or later
3. The MCP Gateway will automatically expose operation descriptions as tool descriptions

No configuration changes required. The router reads descriptions directly from the GraphQL AST and makes them available to all downstream tooling.

• Operations with descriptions become self-documenting MCP tools
• No separate documentation files or custom metadata needed
• AI agents get standardized descriptions for better tool selection

• Standard way to document operations without custom conventions
• Consistent with schema documentation syntax
• Portable across all GraphQL tools that support the spec

GraphQL operations can now describe themselves. At WunderGraph, we're making sure those descriptions work seamlessly with AI tools.

For full MCP integration, see the MCP Gateway Documentation .

Frequently Asked Questions (FAQ)