docs: mcp tools page refactor

docs-website/docs.json

@@ -98,7 +98,7 @@
                 "pages": [
                   "router/mcp",
                   "router/mcp/quickstart",
-                  "router/mcp/operations",
+                  "router/mcp/tools",
                   "router/mcp/configuration",
                   {
                     "group": "OAuth 2.1",
@@ -812,6 +812,10 @@
     {
       "source": "/router/subgraph-error-propagation",
       "destination": "/router/subgraph-data-propagation/subgraph-error-propagation"
+    },
+    {
+      "source": "/router/mcp/operations",
+      "destination": "/router/mcp/tools"
     }
   ]
 }

docs-website/router/mcp.mdx

@@ -56,8 +56,8 @@ The Cosmo MCP Server builds on top of the concept of persisted operations (also
   <Card title="IDE Setup" icon="display-code" href="/router/mcp/ide-setup">
     Connect Claude, Cursor, Windsurf, VS Code, and other AI tools to your MCP server.
   </Card>
-  <Card title="Operations" icon="file-code" href="/router/mcp/operations">
-    Learn how to create, describe, and organize GraphQL operations for AI consumption.
+  <Card title="Tools" icon="wrench" href="/router/mcp/tools">
+    Learn how to define, describe, and organize the tools you expose to AI models.
   </Card>
 </CardGroup>
 
@@ -172,33 +172,14 @@ When an AI model interacts with your MCP endpoint:
 4. Executes tools with appropriate parameters
 5. Receives structured data that it can interpret and use in its responses
 
-## Built-in MCP Tools
+## Tools
 
-The MCP server provides several tools out of the box to help AI models discover and interact with your GraphQL API:
+The MCP server exposes two kinds of tools to AI models:
 
-### Discovery Tools
+- **Built-in tools** provided by the server itself: `get_operation_info` for tool discovery, and the optional `get_schema` and `execute_graphql` for schema access and arbitrary queries.
+- **Tools you create**, each defined by a GraphQL operation. This is the primary way to shape what AI models can do with your API.
 
-<CardGroup cols={2}>
-  <Card title="get_operation_info" icon="circle-info">
-    Retrieves detailed information about a specific GraphQL operation, including its input schema, query structure, and
-    execution guidance. AI models use this to understand how to properly call an operation in real-world scenarios.
-  </Card>
-  <Card title="get_schema" icon="code">
-    Provides the full GraphQL schema as a string. This helps AI models understand the entire API structure. This tool is
-    only available if `expose_schema` is enabled.
-  </Card>
-</CardGroup>
-
-### Execution Tools
-
-<CardGroup cols={2}>
-  <Card title="execute_graphql" icon="play">
-    Executes arbitrary GraphQL queries or mutations against your API. This tool is only available if `enable_arbitrary_operations` is enabled, allowing AI models to craft and execute custom operations beyond predefined ones.
-  </Card>
-  <Card title="execute_operation_*" icon="rocket">
-    For each GraphQL operation in your operations directory, the MCP server automatically generates a corresponding execution tool with the pattern `execute_operation_<operation_name>` (e.g., `execute_operation_get_users`).
-  </Card>
-</CardGroup>
+See the [Tools](/router/mcp/tools) page for the built-in tool reference and how to create your own.
 
 <Card title="Next: Quickstart" icon="arrow-right" href="/router/mcp/quickstart">
   Ready to get started? Follow the quickstart guide to have MCP running in 5 minutes.

docs-website/router/mcp/configuration.mdx

@@ -42,7 +42,7 @@ storage_providers:
 | `exclude_mutations`           | Whether to exclude mutation operations from being exposed                                                                                                                                                                                                                    | `false`          |
 | `enable_arbitrary_operations` | Enables the `execute_graphql` built-in tool, allowing clients to run arbitrary GraphQL operations beyond the pre-defined operation set.                                                                                                                                      | `false`          |
 | `expose_schema`               | Enables the `get_schema` built-in tool, exposing the full GraphQL schema to MCP clients.                                                                                                                                                                                     | `false`          |
-| `omit_tool_name_prefix`       | When enabled, MCP tool names omit the `execute_operation_` prefix. For example, `GetUser` becomes `get_user` instead of `execute_operation_get_user`. See [Operations - Omitting the Tool Name Prefix](/router/mcp/operations#omitting-the-tool-name-prefix).                | `false`          |
+| `omit_tool_name_prefix`       | When enabled, MCP tool names omit the `execute_operation_` prefix. For example, `GetUser` becomes `get_user` instead of `execute_operation_get_user`. See [Tools - Omitting the Tool Name Prefix](/router/mcp/tools#omitting-the-tool-name-prefix).                | `false`          |
 
 For OAuth-specific configuration, see [OAuth 2.1 Authorization](/router/mcp/oauth/overview).
 

docs-website/router/mcp/quickstart.mdx

@@ -158,8 +158,8 @@ The AI model will call the `execute_operation_get_users` tool and return the res
 ## What's Next?
 
 <CardGroup cols={2}>
-  <Card title="Create More Operations" icon="file-code" href="/router/mcp/operations">
-    Learn how to write effective operations with descriptions, handle mutations, and organize your operations directory.
+  <Card title="Create More Tools" icon="wrench" href="/router/mcp/tools">
+    Learn how to write well-described tools, handle mutations, and organize your tools directory.
   </Card>
   <Card title="Full Configuration" icon="sliders-up" href="/router/mcp/configuration">
     Explore all configuration options including session handling, storage providers, and advanced settings.