Editorial improvements for #802

app/en/references/mcp/python/context/page.mdx

@@ -7,6 +7,8 @@ import { Callout } from "nextra/components";
 
 # Context
 
+Reference for the `Context` class used by MCP tools to interact with the server, client, and runtime environment.
+
 The `Context` class is the primary interface for MCP tools to interact with the server, client, and runtime environment. Tools receive a populated `Context` instance as a parameter and should not create instances directly.
 
 `Context` extends `ToolContext` (from `arcade_core`), combining runtime capabilities with tool-specific data.
@@ -34,7 +36,7 @@ These fields inherit from `arcade_core.schema.ToolContext` and the server popula
 | Property | Type | Description |
 |----------|------|-------------|
 | `user_id` | `str \| None` | The user ID for this tool execution |
-| `secrets` | `list` | Secrets available to this tool |
+| `secrets` | `list` | secrets available to this tool |
 | `authorization` | `ToolAuthorizationContext \| None` | Authorization context (token and user info) if the tool requires auth |
 | `metadata` | `dict` | Additional metadata for the tool execution |
 
@@ -162,12 +164,12 @@ Create messages using the connected client's language model.
 
 | Name | Type | Description | Default |
 |------|------|-------------|---------|
-| `messages` | `str \| list[str \| SamplingMessage]` | Messages to send. A plain string is converted to a single user message. | _required_ |
+| `messages` | `str \| list[str \| SamplingMessage]` | Messages to send. The system converts a plain string to a single user message. | _required_ |
 | `system_prompt` | `str \| None` | System prompt | `None` |
 | `include_context` | `str \| None` | Context inclusion (`"none"`, `"thisServer"`, `"allServers"`) | `None` |
 | `temperature` | `float \| None` | Sampling temperature | `None` |
 | `max_tokens` | `int \| None` | Maximum tokens to generate | `None` (defaults to `512`) |
-| `model_preferences` | `ModelPreferences \| str \| list[str] \| None` | Model hints. A string or list of strings is converted to `ModelPreferences` with `ModelHint` entries. | `None` |
+| `model_preferences` | `ModelPreferences \| str \| list[str] \| None` | Model hints. The system converts a string or list of strings to `ModelPreferences` with `ModelHint` entries. | `None` |
 
 ```python
 @tool
@@ -185,7 +187,7 @@ async def summarize(context: Context, text: str) -> str:
 Elicit input from the user through the connected client.
 
 <Callout type="warning">
-  Elicitation requires client support. The schema must have `type: "object"` and properties can only use primitive types (`string`, `number`, `integer`, `boolean`). String properties support `format` values: `email`, `uri`, `date`, `date-time`.
+  Elicitation requires client support. The schema must have `type: "object"` and properties can only use simple types (`string`, `number`, `integer`, `boolean`). String properties support `format` values: `email`, `uri`, `date`, `date-time`.
 </Callout>
 
 **Methods:**
@@ -236,12 +238,12 @@ Send notifications to the connected client, such as list-changed events.
 async def register_new_tool(context: Context) -> str:
     # ... register a tool at runtime ...
     await context.notifications.tools.list_changed()
-    return "Tool registered"
+    return "tool registered"
 ```
 
 ## Additional properties
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `context.request_id` | `str \| None` | The unique identifier for the current MCP request |
-| `context.session_id` | `str \| None` | The unique identifier for the current MCP session |
+| `context.session_id` | `str \| None` | The unique identifier for the current MCP session |

app/en/references/mcp/python/errors/page.mdx

@@ -5,7 +5,11 @@ description: "Exception types raised by the MCP server and re-exported from arca
 
 # Errors
 
-Domain-specific exception types for the MCP server. All exceptions are defined in `arcade_mcp_server.exceptions`.
+Exception types raised by the MCP server and re-exported from arcade-core.
+
+Domain-specific exception types for the MCP server. All exceptions live in `arcade_mcp_server.exceptions`.
+
+This reference covers the complete hierarchy of MCP exceptions you'll encounter when building MCP servers with Arcade. You'll use these exceptions to handle errors in your tool implementations and understand failures in server operations. The exceptions organize into runtime errors for server operations and context errors for entity management.
 
 ## MCP exception hierarchy
 
@@ -131,7 +135,7 @@ Error during tool execution (wraps the underlying exception).
 
 ### `FatalToolError`
 
-A fatal error that should not be retried.
+A fatal error that you should not retry.
 
 ### `RetryableToolError`
 
@@ -194,5 +198,4 @@ except NotFoundError:
 except TransportError:
     print("Transport layer error")
 except MCPError:
-    print("General MCP error")
-```
+    print("General MCP error")

app/en/references/mcp/python/middleware/page.mdx

@@ -5,7 +5,11 @@ description: "Base interfaces and built-in middleware for intercepting and modif
 
 # Middleware
 
-Middleware allows you to intercept and modify requests and responses at various stages of processing. Each handler receives a `MiddlewareContext` and a `call_next` function to invoke the next handler in the chain.
+Middleware intercepts and modifies requests and responses at specific stages of processing.
+
+This reference covers the base middleware classes, built-in middleware implementations, and utility functions for composing middleware chains. You'll use this when building custom middleware for logging, error handling, authentication, or request modification. The middleware system provides typed handlers for each MCP method and supports chaining multiple middleware together.
+
+Each handler receives a `MiddlewareContext` and a `call_next` function to invoke the next handler in the chain.
 
 ## Base classes
 
@@ -25,7 +29,7 @@ Each handler receives the context and a `call_next` function. Call `await call_n
 async __call__(context, call_next)
 ```
 
-Main entry point. Orchestrates the middleware chain by building a handler chain from method-specific and type-specific handlers, then invoking it.
+Main entry point. Orchestrates the middleware chain by building a handler chain from method-specific and type-specific handlers, then invokes it.
 
 ##### `on_message`
 
@@ -111,16 +115,16 @@ Handle `prompts/list` requests. Override to filter or modify the prompt list.
 
 **`arcade_mcp_server.middleware.base.MiddlewareContext`**
 
-A generic dataclass (`Generic[T]`) passed through the middleware chain. Contains the message being processed and metadata about the request.
+A generic dataclass (`Generic[T]`) passed through the middleware chain. Contains the message that the system processes and metadata about the request.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `message` | `T` | The message being processed |
+| `message` | `T` | The message that the system processes |
 | `mcp_context` | `Any \| None` | The MCP `Context` instance (when in a request context) |
 | `source` | `"client" \| "server"` | Message origin |
 | `type` | `"request" \| "notification"` | Message type |
-| `method` | `str \| None` | MCP method name (e.g., `"tools/call"`) |
-| `timestamp` | `datetime` | When the context was created (UTC) |
+| `method` | `str \| None` | MCP method name (for example, `"tools/call"`) |
+| `timestamp` | `datetime` | When the developer created the context (UTC) |
 | `request_id` | `str \| None` | JSON-RPC request ID |
 | `session_id` | `str \| None` | MCP session ID |
 | `metadata` | `dict[str, Any]` | Additional metadata that middleware can add to |
@@ -149,7 +153,7 @@ A `Protocol` representing the next handler in the middleware chain. Signature: `
 arcade_mcp_server.middleware.base.compose_middleware(*middleware)
 ```
 
-Compose multiple `Middleware` instances into a single handler function. The middleware are applied in reverse order, so the **first** middleware in the argument list is the outermost (runs first on request, last on response).
+Compose multiple `Middleware` instances into a single handler function. The system applies the middleware in reverse order, so the **first** middleware in the argument list is the outermost (runs first on request, last on response).
 
 **Parameters:**
 
@@ -197,7 +201,7 @@ Overrides:
 
 ## Examples
 
-### Creating custom middleware
+### Create custom middleware
 
 ```python
 import time
@@ -215,7 +219,7 @@ class TimingMiddleware(Middleware):
             context.metadata["elapsed_ms"] = round(elapsed_ms, 2)
 ```
 
-### Passing custom middleware to MCPServer
+### Pass custom middleware to MCPServer
 
 ```python
 from arcade_core.catalog import ToolCatalog
@@ -232,7 +236,7 @@ server = MCPServer(
 )
 ```
 
-### Using compose_middleware
+### Use compose_middleware
 
 ```python
 from arcade_mcp_server.middleware.base import compose_middleware
@@ -243,5 +247,4 @@ composed = compose_middleware(
     ErrorHandlingMiddleware(mask_error_details=False),
     LoggingMiddleware(log_level="INFO"),
     TimingMiddleware(),
-)
-```
+)

app/en/references/mcp/python/page.mdx

@@ -7,6 +7,8 @@ import { Callout } from "nextra/components";
 
 # Arcade MCP Server - Python overview
 
+This page covers the arcade-mcp-server Python package and its main MCPApp class.
+
 `arcade-mcp-server` is Arcade's framework for building MCP servers. It provides a clean, minimal API
 to build MCP servers programmatically. The main entry point is `MCPApp`, which handles tool
 collection, server configuration, and transport setup.
@@ -34,7 +36,7 @@ if __name__ == "__main__":
 **`arcade_mcp_server.mcp_app.MCPApp`**
 
 A FastAPI-like interface for building MCP servers. The app collects tools and configuration, then
-lazily creates the server and transport when `run()` is called.
+lazily creates the server and transport when `run()` calls them.
 
 ### `__init__`
 
@@ -69,7 +71,7 @@ Initialize the MCP app.
 | `host` | `str` | Host for HTTP transport | `'127.0.0.1'` |
 | `port` | `int` | Port for HTTP transport | `8000` |
 | `reload` | `bool` | Enable auto-reload for development (HTTP only) | `False` |
-| `auth` | `ResourceServerValidator \| None` | Resource Server validator for front-door authentication (HTTP only) | `None` |
+| `auth` | `ResourceServerValidator \| None` | Resource server validator for front-door authentication (HTTP only) | `None` |
 | `**kwargs` | `Any` | Additional server configuration passed to the underlying `MCPServer` | `{}` |
 
 ### Properties
@@ -79,7 +81,7 @@ Initialize the MCP app.
 Runtime and build-time tools API. Returns a `_ToolsAPI` object with async methods: `add()`, `update()`, `remove()`, `list()`.
 
 <Callout type="warning">
-  The runtime tools API (`app.tools.add()`, etc.) requires a server to be bound via `app.server`. It is only available after the server has started. Use the `@app.tool` decorator or `app.add_tool()` for build-time tool registration.
+  The runtime tools API (`app.tools.add()`, etc.) requires you to bind a server via `app.server`. It is only available after the server has started. Use the `@app.tool` decorator or `app.add_tool()` for build-time tool registration.
 </Callout>
 
 #### `prompts`
@@ -104,7 +106,7 @@ def my_tool(...) -> ...:
     ...
 ```
 
-Decorator for registering tools. Can be used with or without arguments.
+Decorator for registering tools. Can use with or without arguments.
 
 **Parameters:**
 
@@ -142,7 +144,7 @@ Add a tool for build-time materialization (before the server starts). Accepts th
 app.add_tools_from_module(module)
 ```
 
-Add all `@tool`-decorated functions from a Python module to the catalog.
+Add all `@tool`-decorated functions from a Python module to the catalog that has already registered them.
 
 **Parameters:**
 
@@ -294,5 +296,4 @@ app = MCPApp(name="my_server", version="1.0.0")
 app.add_tools_from_module(my_tools)
 
 if __name__ == "__main__":
-    app.run()
-```
+    app.run()

app/en/references/mcp/python/server/page.mdx

@@ -11,13 +11,15 @@ import { Callout } from "nextra/components";
   Most users should use [`MCPApp`](/references/mcp/python) instead of `MCPServer` directly. `MCPServer` is a low-level API for advanced use cases.
 </Callout>
 
+This reference covers the low-level `MCPServer` class for advanced MCP server implementations.
+
 The `MCPServer` class is the core server implementation that handles MCP protocol messages, middleware orchestration, and component management for tools, resources, and prompts.
 
 ## `MCPServer`
 
 **`arcade_mcp_server.server.MCPServer`**
 
-MCP Server with middleware and context support.
+MCP server with middleware and context support.
 
 This server provides:
 - Middleware chain for extensible request processing
@@ -57,14 +59,14 @@ Initialize the MCP server.
 | `title` | `str \| None` | Server title for display. Falls back to settings, then to `name`. | `None` |
 | `instructions` | `str \| None` | Server instructions sent to clients during initialization | `None` |
 | `settings` | `MCPSettings \| None` | MCP settings. Loaded from environment if not provided. | `None` |
-| `middleware` | `list[Middleware] \| None` | Custom middleware to add to the chain (appended after built-in middleware) | `None` |
+| `middleware` | `list[Middleware] \| None` | Custom middleware to add to the chain (appends after built-in middleware) | `None` |
 | `lifespan` | `Callable \| None` | Lifespan manager function for startup/shutdown hooks | `None` |
 | `auth_disabled` | `bool` | Disable authentication | `False` |
 | `arcade_api_key` | `str \| None` | Arcade API key. Overrides settings and credentials file. | `None` |
 | `arcade_api_url` | `str \| None` | Arcade API URL. Overrides settings. | `None` |
 
 <Callout type="info">
-  The server automatically adds `ErrorHandlingMiddleware` and (if enabled in settings) `LoggingMiddleware` to the middleware chain. Custom middleware is appended after these built-in middleware.
+  The server automatically adds `ErrorHandlingMiddleware` and (if enabled in settings) `LoggingMiddleware` to the middleware chain. Custom middleware appends after these built-in middleware.
 </Callout>
 
 ### Properties
@@ -176,5 +178,4 @@ async def main():
         await server.stop()
 
 if __name__ == "__main__":
-    asyncio.run(main())
-```
+    asyncio.run(main())