Skip to content

Add section on SDL docstrings for tool definitions #376

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Add section on SDL docstrings for tool definitions #376

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/source/best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

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.

Check notice on line 16 in docs/source/best-practices.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/best-practices.mdx#L16 

Link text should be descriptive of the linked content.

```suggestion
- **Tool Descriptions**: The schema provides type information used to generate tool descriptions. You can override these descriptions by [adding SDL docstrings](/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.

Expand Down
17 changes: 16 additions & 1 deletion docs/source/define-tools.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,4 +233,19 @@

```sh title="Example command using introspection"
apollo-mcp-server <path to the preceding config>
```
```

Check failure on line 236 in docs/source/define-tools.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/define-tools.mdx#L236 

Prose content, such as headings and paragraphs, should not be inside a code block.

```suggestion

```

## Adding SDL Docstrings

Check warning on line 238 in docs/source/define-tools.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/define-tools.mdx#L238 

Headings must use sentence casing.

```suggestion
## 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.

Check failure on line 240 in docs/source/define-tools.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/define-tools.mdx#L240 

"defintions" is a typo and should be "definitions".

```suggestion
Apollo MCP Server also supports adding [SDL docstrings](apollo-server/schema/schema#descriptions-docstrings) to tool definitions. 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.
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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.

Check notice on line 242 in docs/source/define-tools.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/define-tools.mdx#L242 

Use present tense ("can make") instead of future tense ("will be able to make") for conciseness and clarity.

```suggestion
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 so your MCP client can make better choices about which tool to use.
```

```graphql
# Get the detailed weather forecast for a given location
query GetForecast($coordinate: InputCoordinate!) {
forecast(coordinate: $coordinate) {
detailed
}
}
Comment on lines +245 to +250
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be great if the example operation shows that docstrings can also be added for input arguments.

Suggested change
# 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
}
}

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
      }
    }
  }
}

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When we add these to an operation / tool though, should it be referred to as docstrings? Technically they are comments

```

Check failure on line 251 in docs/source/define-tools.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/define-tools.mdx#L251 

Prose content, such as headings and paragraphs, should not be inside a code block.

```suggestion

```