From bdb71a7b9c930722e775de16d322669029cb32e6 Mon Sep 17 00:00:00 2001 From: Joseph Caudle Date: Mon, 22 Sep 2025 20:16:44 -0400 Subject: [PATCH] Add section on SDL docstrings for tool definitions 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/source/best-practices.mdx | 2 +- docs/source/define-tools.mdx | 17 ++++++++++++++++- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/source/best-practices.mdx b/docs/source/best-practices.mdx index 6f3ce712..ced7c261 100644 --- a/docs/source/best-practices.mdx +++ b/docs/source/best-practices.mdx @@ -13,7 +13,7 @@ This feature is in [preview](/graphos/resources/feature-launch-stages#preview). The schema is required for: -- **Tool Descriptions**: The schema provides type information used to generate tool descriptions. You can override these descriptions by adding comments to your operation files. +- **Tool Descriptions**: The schema provides type information used to generate tool descriptions. You can override these descriptions by [adding comments](/apollo-mcp-server/define-tools#adding-sdl-docstrings) to your operation files. - **Input Validation**: The schema is used to translate GraphQL input types into JSON Schema, ensuring that AI models provide correctly formatted inputs. - **Introspection Support**: If you enable the `introspection` option, the schema is used to provide information about available types and operations to AI models. diff --git a/docs/source/define-tools.mdx b/docs/source/define-tools.mdx index 3a104d76..36937e64 100644 --- a/docs/source/define-tools.mdx +++ b/docs/source/define-tools.mdx @@ -233,4 +233,19 @@ introspection: ```sh title="Example command using introspection" apollo-mcp-server -``` \ No newline at end of file +``` + +## 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. + +Docstrings are a great way to provide more specific information about what your operations do than the default description provided by your GraphQL operation. Use this feature to describe the options available from the tool or explain why the operation is useful and your MCP client will be able to make better choices of which tool to use. + +```graphql +# Get the detailed weather forecast for a given location +query GetForecast($coordinate: InputCoordinate!) { + forecast(coordinate: $coordinate) { + detailed + } +} +```