Providing custom instructions/hints for GraphQL query generation

[michalpie]

When working with large and complex GraphQL schemas, the model can sometimes struggle to generate accurate queries based solely on introspection and search tools. Our schema, for instance, has several non-obvious patterns and relationships that are difficult for the model to infer on its own.

Based on our experiments, providing the model with specific hints or instructions about the schema's structure and common query patterns dramatically improves the accuracy and reliability of the generated GraphQL queries.

I'd like to use a mechanism to inject this custom guidance into the model's context, if such mechanism exists. Otherwise to propose it:

Allow users to override the default descriptions for the built-in tools, especially the execute tool. By modifying its description, we could embed our hints directly into the context the model uses when it considers executing a GraphQL query.

For example, we could change the execute tool's description from its default to something like:
"Executes a GraphQL query. IMPORTANT HINT: To get a user's active cart, always query the 'carts' connection with a filter, like 'carts(where: { status: ACTIVE })'. The 'shoppingCart' field is deprecated."

Example Use Case
Imagine a schema where fetching a user's active shopping cart requires a specific filter:

Naive/Incorrect Query: query { user(id: "123") { shoppingCart { id } } }

Correct Query: query { user(id: "123") { carts(where: { status: ACTIVE }) { id } } }

Without guidance, the model might default to the simpler but incorrect field. A custom hint could explicitly guide it to use the correct pattern, preventing errors and improving the user experience.

[swcollard]

Thanks for this feedback and suggestion! The team is currently looking at different ways we can help the LLM craft better operations. We'll include this as an idea and let you know what our plans are. cc @esilverm

[michalpie]

Great, this library is already fantastic.

Maybe you could add an option to pass user customizable hints to the tool descriptions (instead of overriding the whole description), which could be appended to the descriptions.

Also, MCP level "instructions" field could be configured (but this is not enough as some clients like Copilot do not use it).

[michalpie]

I have created this draft PR (#359) with an initial implementation of hints for the execute tool only. If you are accept this approach, I can extend it to other tools.

[kbychu]

@michalpie

Thanks for this proposal! The shopping cart example really illustrates the challenge with deprecated fields and non-obvious patterns.
Have you considered putting these hints at the client level instead? For example:

Cursor: Add to project-level system prompts
Claude Desktop: Add to custom instructions
Custom agents: Include in their base configuration

This would let you start using hints immediately, customize per AI model, and iterate without touching server infrastructure.

Some additional questions:

• What specific benefits would server-side provide that client-side wouldn't? I am guessing it may be hard to get everyone to configure their client correctly.
• Would a separate shared hint library (that clients could reference) work instead?

[michalpie]

@kbychu

Client-side hints
In practice, relying on client-side configuration quickly becomes difficult to manage at scale. Imagine a company running several MCP servers that expose corporate data to hundreds of employees. Every employee would need to carefully configure their prompts, and then update those configurations whenever the MCP (e.g., the GraphQL model) changes. That introduces a lot of room for inconsistency and drift.

Shared library approach
A shared hint library does sound like a step in the right direction, but it also raises challenges:

• Not every client supports this type of integration.
• To my knowledge, there isn’t yet a common standard for distributing or consuming such libraries across clients.
• Even with a library, you’d still need to ensure every client is updated and correctly wired into it.

This is why server-side hints feel valuable: they centralize the configuration, keep clients lightweight, and ensure consistency across the organization without requiring each user to manage their own setup.