Merge pull request #383 from apollographql/mm/docs-define-tools

Docs: Clarify examples for defining tools

Author: mabuyo

docs/source/define-tools.mdx

@@ -48,24 +48,25 @@ You can also use the `operations` option to specify a directory. The server then
 
 Files and directories specified with `operations` are hot reloaded. When you specify a file, the MCP tool is updated when the file contents are modified. When you specify a directory, operations exposed as MCP tools are updated when files are added, modified, or removed from the directory.
 
-### From Operation Collection
+### From an operation collection
 
-For graphs managed by GraphOS, Apollo MCP Server can get operations from an [Operation Collection](https://www.apollographql.com/docs/graphos/platform/explorer/operation-collections).
+For graphs managed by GraphOS, Apollo MCP Server can get operations from an [operation collection](/graphos/platform/explorer/operation-collections).
 
-To use a GraphOS Operation Collection, you must:
+To use a GraphOS operation collection, you must set your graph credentials `APOLLO_GRAPH_REF` and `APOLLO_KEY` as environment variables.
 
-- Set `APOLLO_GRAPH_REF` and `APOLLO_KEY` environment variables for a GraphOS graph
+Use the `operations.source: collection` option to specify that tools should be loaded from an operation collection.
 
-Each variant will have its own default MCP Tools Collection, but you can specify any shared collection by using `operations` with `operations.source: collection`.
-Apollo MCP Server automatically fetches the default collection if no ID is specified.
+Specify the collection to use with the `operations.id` option. To view the ID of a collection, click the ••• button next to its entry, select **View details**, and copy the **Collection ID**.
 
-```yaml title="Example config file for using a GraphOS Operation Collection"
+Each graph variant has its own default collection called **Default MCP Tools**. To use this default collection, specify `operations.id: default`.
+
+```yaml title="Example config file for using the default MCP Tools operation collection"
 operations:
   source: collection
-  id: <collection-id>
+  id: default
 ```
 
-The MCP Server supports hot reloading of the GraphOS Operation Collection, so it can automatically pick up changes from GraphOS without restarting.
+The MCP Server supports hot reloading of the GraphOS operation collection, so it can automatically pick up changes from GraphOS without restarting.
 
 ### From persisted query manifests
 
@@ -75,34 +76,19 @@ Set the persisted query manifest file for the MCP Server with the `operations` o
 
 An example manifest is available in the [GitHub repo](https://github.com/apollographql/apollo-mcp-server/tree/main/graphql/weather/persisted_queries).
 
-<ExpansionPanel title="Example command using --manifest">
-
-From the root of a local MCP Server repo, run the `apollo-mcp-server` binary with the example persisted query manifest, `graphql/weather/persisted_queries/apollo.json`:
-
-```yaml title="Example config for using Persisted Query Manifest"
-headers:
-  "apollographql-client-name": "my-web-app"
+```yaml title="Example config for using persisted query manifest"
 operations:
   source: manifest
-  path: <absolute path to this local repo>/graphql/weather/persisted_queries/apollo.json
-schema:
-  source: local
-  path: <absolute path to this local repo>/graphql/weather/api.graphql
+  path: <PATH/TO/persisted-queries-manifest.json>
 ```
 
-```sh showLineNumbers=false
-apollo-mcp-server <path to the preceding config>
-```
-
-</ExpansionPanel>
-
 ### From GraphOS-managed persisted queries
 
 For graphs managed by GraphOS, Apollo MCP Server can get operations by reading persisted queries from GraphOS. The MCP Server uses Apollo Uplink to access the persisted queries.
 
-To use GraphOS persisted queries, you must:
+To use GraphOS persisted queries, you must set your graph credentials `APOLLO_GRAPH_REF` and `APOLLO_KEY` as environment variables.
 
-- Set `APOLLO_GRAPH_REF` and `APOLLO_KEY` environment variables for a GraphOS graph
+Use the `operations.source: uplink` option to specify that tools should be loaded from GraphOS-managed persisted queries.
 
 <Tip>
 
@@ -111,17 +97,8 @@ Use a [contract variant](/graphos/platform/schema-management/delivery/contracts/
 </Tip>
 
 ```yaml title="Example config using GraphOS-managed persisted queries"
-headers:
-  "apollographql-client-name": "my-web-app"
 operations:
   source: uplink
-schema:
-  source: local
-  path: <absolute path to this git repo>/graphql/weather/api.graphql
-```
-
-```sh title="Example command using GraphOS-managed persisted queries"
-apollo-mcp-server <path to the preceding config>
 ```
 
 The MCP Server supports hot reloading of GraphOS-managed persisted queries, so it can automatically pick up changes from GraphOS without restarting.
@@ -130,16 +107,23 @@ If you register a persisted query with a specific client name instead of `null`,
 
 Use the `headers` option when running the MCP Server to pass the header to the router. The default name of the header expected by the router is `apollographql-client-name`. To use a different header name, configure `telemetry.apollo.client_name_header` in router YAML configuration.
 
+```yaml title="Example config using GraphOS-managed persisted queries" {1-2}
+headers:
+  "apollographql-client-name": "my-web-app"
+operations:
+  source: uplink
+```
+
 ## Introspection tools
 
 In addition to defining specific tools for pre-defined GraphQL operations, Apollo MCP Server supports introspection tools that enable AI agents to explore the graph schema and execute operations dynamically.
 
 You can enable the following introspection tools:
 
-- `introspect` - allows the AI model to introspect the schema of the GraphQL API by providing a specific type name to get information about, and a depth parameter to determine how deep to traverse the subtype hierarchy. The AI model can start the introspection by looking up the top-level `Query` or `Mutation` type.
-- `search` - allows the AI model to search for type information by providing a set of search terms. This can result in fewer tool calls than `introspect`, especially if the desired type is deep in the type hierarchy of the schema. Search results include all the parent type information needed to construct operations involving the matching type.
-- `validate` - validates a GraphQL operation against the schema without executing it. This allows AI models to verify that their operations are syntactically correct and conform to the schema before execution, preventing unintended side effects. Operations should be validated prior to calling the `execute` tool.
-- `execute` - executes an operation on the GraphQL endpoint
+- `introspect`: allows the AI model to introspect the schema of the GraphQL API by providing a specific type name to get information about, and a depth parameter to determine how deep to traverse the subtype hierarchy. The AI model can start the introspection by looking up the top-level `Query` or `Mutation` type.
+- `search`: allows the AI model to search for type information by providing a set of search terms. This can result in fewer tool calls than `introspect`, especially if the desired type is deep in the type hierarchy of the schema. Search results include all the parent type information needed to construct operations involving the matching type.
+- `validate`: validates a GraphQL operation against the schema without executing it. This allows AI models to verify that their operations are syntactically correct and conform to the schema before execution, preventing unintended side effects. Operations should be validated prior to calling the `execute` tool.
+- `execute`: executes an operation on the GraphQL endpoint
 
 The MCP client can use these tools to provide schema information to the model and its context window, and allow the model to execute GraphQL operations based on that schema.
 
@@ -197,8 +181,4 @@ introspection:
     leaf_depth: 1
   validate:
     enabled: true
-```
-
-```sh title="Example command using introspection"
-apollo-mcp-server <path to the preceding config>
 ```