Merge pull request #201 from apollographql/pubmodmatt/search_doc

Add documentation for the search tool

Author: DaleSeo

docs/source/best-practices.mdx

@@ -18,7 +18,7 @@ When running Apollo MCP Server with GraphOS, use contract variants whenever poss
 In particular, we strongly recommend contract variants when using:
 
 - [GraphOS-managed persisted queries](/apollo-mcp-server/guides#from-graphos-managed-persisted-queries)
-- [Introspection](/apollo-mcp-server/guides#from-schema-introspection)
+- [Introspection](/apollo-mcp-server/guides#introspection-tools)
 
 ## Send client name header when using persisted queries
 

docs/source/guides/index.mdx

@@ -153,13 +153,14 @@ 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.
 
-### From schema introspection
+## Introspection tools
 
-For use cases where not all operations can be pre-defined, Apollo MCP Server supports tool creation based on introspection of the graph schema. This allows AI agents to explore a graph and execute operations dynamically.
+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.
 
-To enable these schema-aware tools, run the MCP Server with the `introspection` option, which exposes two new tools:
+You can enable the following introspection tools:
 
-- `introspect` - returns information about schema types
+- `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.
 - `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.

docs/source/quickstart.mdx

@@ -189,7 +189,7 @@ If you're still having issues:
 See the [user guide](/apollo-mcp-server/guides) to learn how to create tools from:
 - [Operation files](/apollo-mcp-server/guides#from-operation-files)
 - [Persisted query manifests](/apollo-mcp-server/guides/#from-persisted-query-manifests)
-- [Schema introspection](/apollo-mcp-server/guides/#from-schema-introspection)
+- [Schema introspection](/apollo-mcp-server/guides/#introspection-tools)
 
 When you are ready, [deploy the MCP server](https://www.apollographql.com/docs/apollo-mcp-server/guides#deploying-the-mcp-server).