Add section on SDL docstrings for tool definitions #376
Conversation
Updated best practices and tool definition docs to reference and explain the use of SDL docstrings for improving tool descriptions. Added guidance and an example to help users document their GraphQL operations for better LLM integration.
✅ Docs preview readyThe preview is ready to be viewed. View the preview File Changes 0 new, 3 changed, 0 removedBuild ID: cc65526d70e7908e54329e93 URL: https://www.apollographql.com/docs/deploy-preview/cc65526d70e7908e54329e93 |
|
|
||
| ## Adding SDL Docstrings | ||
|
|
||
| Apollo MCP Server also supports adding [SDL docstrings](apollo-server/schema/schema#descriptions-docstrings) to tool defintions. This form of documentation can make it easier for LLMs to determine which tool is best for any given prompt. Apollo recommends adding docstrings to any tool you define so you can be sure your MCP tools are used appropriately. |
There was a problem hiding this comment.
Apollo recommends adding docstrings to any tool you define so you can be sure your MCP tools are used appropriately.
I'm not sure this should be our primary guidance. In my view, it's more effective to encourage deverlops to write clear, descriptive schema documentation from the start. If the schema itself is well-documented, those descriptions can be leveraged across all MCP server instances, making additional docstrings less necessary. This approach also reinforces best practices in GraphQL, where thorough schema descriptions have always been the standard. I'd prefer we nudge users toward improving their schema documentation rather than relying on docstrings as a workaround.
| # Get the detailed weather forecast for a given location | ||
| query GetForecast($coordinate: InputCoordinate!) { | ||
| forecast(coordinate: $coordinate) { | ||
| detailed | ||
| } | ||
| } |
There was a problem hiding this comment.
It would be great if the example operation shows that docstrings can also be added for input arguments.
| # Get the detailed weather forecast for a given location | |
| query GetForecast($coordinate: InputCoordinate!) { | |
| forecast(coordinate: $coordinate) { | |
| detailed | |
| } | |
| } | |
| # Get the detailed weather forecast for a given location | |
| query GetForecast( | |
| # latitude and longitude | |
| $coordinate: InputCoordinate! | |
| ) { | |
| forecast(coordinate: $coordinate) { | |
| detailed | |
| } | |
| } |
There was a problem hiding this comment.
Watson shared this code snippet as an example.
# Get the schema change proposals related to a given graph id
# If the count of proposals returned is less than the totalCount, use offset to paginate through the rest of proposals
query GetSchemaChangeProposals(
$graphId: ID!
# Valid values: "APPROVED", "CLOSED", "DRAFT", "IMPLEMENTED", "OPEN".
# Default to ["OPEN"] if not provided.
$filterByStatus: [ProposalStatus!]
# Filter proposals to only affected subgraph names
$filterBySubgraph: [String!]
# Filter proposals to specific source variants
$filterBySourceVariant: [String!]
# Use for pagination
$offset: Int
# Defaults to 5, don't exceed 25
$limit: Int = 5
) {
graph(id: $graphId) {
id
name
proposals(
filterBy: {
status: $filterByStatus
subgraphs: $filterBySubgraph
sourceVariants: $filterBySourceVariant
}
offset: $offset
limit: $limit
) {
totalCount
proposals {
id
createdAt
activities {
nodes {
activity
createdAt
}
}
status
displayName
}
}
}
}
There was a problem hiding this comment.
When we add these to an operation / tool though, should it be referred to as docstrings? Technically they are comments
Updated best practices and tool definition docs to reference and explain the use of SDL docstrings for improving tool descriptions. Added guidance and an example to help users document their GraphQL operations for better LLM integration.