@mastra/mcp-docs-server 1.2.11 → 1.2.12-alpha.0

package/.docs/reference/streaming/agents/streamUntilIdle.md

@@ -32,7 +32,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-> **Info:** `streamUntilIdle()` requires both a [`BackgroundTaskManager`](https://mastra.ai/reference/configuration) and a [memory](https://mastra.ai/docs/memory/overview) backend. Without either, it falls through to a plain `agent.stream()` call.
+> **Info:** `streamUntilIdle()` requires both a [`BackgroundTaskManager`](https://mastra.ai/reference/configuration) and a [memory](https://mastra.ai/docs/memory/overview) backend. Without either, it uses a plain `agent.stream()` call.
 
 ## Parameters
 
@@ -54,7 +54,7 @@ For every other option (`maxSteps`, `modelSettings`, `toolChoice`, `outputProces
 
 ### Aggregate properties caveat
 
-`streamUntilIdle()` returns a proxy over the first turn's `MastraModelOutput`. Only `fullStream` is replaced with a combined stream that spans every continuation. Every other property — `text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()` — resolves against the **first turn's** internal buffer.
+`streamUntilIdle()` returns a proxy over the first turn's `MastraModelOutput`. Only `fullStream` is replaced with a combined stream that spans every continuation. Every other property (`text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, and `getFullOutput()`) resolves against the **first turn's** internal buffer.
 
 If you need an aggregate view across all continuations, consume `fullStream` yourself and accumulate.
 

package/.docs/reference/streaming/workflows/observeStream.md

@@ -28,7 +28,7 @@ for await (const chunk of stream) {
 
 ## Stream events
 
-The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
+The stream emits event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
 
 - **`workflow-start`**: Workflow execution begins
 - **`workflow-step-start`**: A step begins execution

package/.docs/reference/streaming/workflows/resumeStream.md

@@ -60,7 +60,7 @@ if (result!.status === 'suspended') {
 
 ## Stream events
 
-The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
+The stream emits event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
 
 - **`workflow-start`**: Workflow execution begins
 - **`workflow-step-start`**: A step begins execution

package/.docs/reference/streaming/workflows/stream.md

@@ -86,7 +86,7 @@ console.log('Status:', stream.status)
 
 ## Stream events
 
-The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
+The stream emits event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
 
 - **`workflow-start`**: Workflow execution begins
 - **`workflow-step-start`**: A step begins execution

package/.docs/reference/streaming/workflows/timeTravelStream.md

@@ -2,7 +2,7 @@
 
 # Run.timeTravelStream()
 
-The `.timeTravelStream()` method re-executes a workflow starting from any specific step with streaming events. This allows you to receive real-time updates during time travel execution while maintaining full visibility into each step's progress.
+The `.timeTravelStream()` method re-executes a workflow starting from any specific step with streaming events. You can receive real-time updates during time travel execution while maintaining full visibility into each step's progress.
 
 ## Usage example
 
@@ -39,7 +39,7 @@ All parameters are the same as [`Run.timeTravel()`](https://mastra.ai/reference/
 
 ## Stream events
 
-The stream emits various workflow events during execution:
+The stream emits workflow events during execution:
 
 - `workflow-step-start`: Emitted when a step begins execution
 - `workflow-step-finish`: Emitted when a step completes successfully

package/.docs/reference/templates/overview.md

@@ -2,7 +2,7 @@
 
 # Overview
 
-This reference provides comprehensive information about Mastra templates, including how to use existing templates, create your own, and contribute to the community ecosystem.
+This reference explains how to use existing Mastra templates and create your own. It also covers contributing templates to the community ecosystem.
 
 Mastra templates are pre-built project structures that demonstrate specific use cases and patterns. They provide:
 

package/.docs/reference/tools/brightdata.md

@@ -2,7 +2,7 @@
 
 # Bright Data tools
 
-The `@mastra/brightdata` package wraps the [Bright Data SDK](https://github.com/brightdata/bright-data-sdk-node) as Mastra-compatible tools. It exposes factory functions for web search and web fetch — each returning a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.
+The `@mastra/brightdata` package wraps the [Bright Data SDK](https://github.com/brightdata/bright-data-sdk-node) as Mastra-compatible tools. It exposes factory functions for web search and web fetch. Each function returns a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.
 
 The search tool is backed by Bright Data's [SERP API](https://brightdata.com/products/serp-api) and the fetch tool by [Web Unlocker](https://brightdata.com/products/web-unlocker). Both bypass bot detection and CAPTCHAs.
 

package/.docs/reference/tools/create-tool.md

@@ -2,7 +2,7 @@
 
 # createTool()
 
-The `createTool()` function is used to define custom tools that your Mastra agents can execute. Tools extend an agent's capabilities by allowing it to interact with external systems, perform calculations, or access specific data.
+The `createTool()` function is used to define custom tools that your Mastra agents can execute. Tools extend an agent's capabilities by allowing it to interact with external systems or perform calculations. They can also access specific data.
 
 ## Usage example
 

package/.docs/reference/tools/graph-rag-tool.md

@@ -51,7 +51,7 @@ const graphTool = createGraphRAGTool({
 
 **graphOptions.restartProb** (`number`): Probability of restarting random walk from query node. (Can be set at creation or overridden at runtime.)
 
-**providerOptions** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
+**providerOptions** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
 
 **vectorStore** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, vectorStoreName becomes optional.
 

package/.docs/reference/tools/mcp-client.md

@@ -125,7 +125,7 @@ const mcp = new MCPClient({
 })
 ```
 
-Per the MCP specification, **clients MUST consider tool annotations to be untrusted unless they come from trusted servers**. Annotations are advisory hints, not a security boundary — a malicious or buggy server can claim a tool is read-only when it isn't. Only use annotations to relax approval requirements for servers you trust.
+Per the MCP specification: **clients MUST consider tool annotations to be untrusted unless they come from trusted servers**. Annotations are advisory hints and provide no security boundary. A malicious or buggy server can claim a tool is read-only when it isn't. Only use annotations to relax approval requirements for servers you trust.
 
 The same annotations are also exposed on the tools returned by `listTools()` and `listToolsets()` under `tool.mcp.annotations`, so you can inspect them when wiring tools into an agent.
 
@@ -182,7 +182,7 @@ console.log(errors)
 
 ### `listToolsets()`
 
-Returns an object mapping namespaced tool names (in the format `serverName.toolName`) to their tool implementations. Intended to be passed dynamically into the generate or stream method.
+Returns an object mapping namespaced tool names (in the format `serverName.toolName`) to their tool implementations. Intended to be passed at runtime into the generate or stream method.
 
 ```typescript
 const res = await agent.stream(prompt, {
@@ -227,9 +227,9 @@ getServerAuthState(serverName: string): 'needs-auth' | 'authorized' | undefined
 
 ### `cancelAuthentication()`
 
-Cancels an in-progress `authenticate()` flow for a server, so an abandoned browser authorization does not leave the client waiting indefinitely. It aborts the flow (including its setup phase, before the callback server binds), closes the local callback server if one is listening, and the pending `authenticate()` call rejects. Returns `true` if a flow was cancelled, or `false` when no flow was in progress.
+Cancels an in-progress `authenticate()` flow for a server, so an abandoned browser authorization doesn't leave the client waiting indefinitely. It aborts the flow (including its setup phase, before the callback server binds), closes the local callback server if one is listening, and the pending `authenticate()` call rejects. Returns `true` if a flow was cancelled, or `false` when no flow was in progress.
 
-The resulting `getServerAuthState()` depends on how far the flow had progressed: a flow cancelled after the server rejected the connection with `401` stays at `'needs-auth'` and can be retried immediately, while a flow cancelled during the setup phase — before any connection was attempted — leaves the state unchanged (typically `undefined`).
+The resulting `getServerAuthState()` depends on how far the flow progressed. A flow cancelled after a `401` rejection stays at `'needs-auth'` and can be retried immediately. Cancellation during setup leaves the state unchanged (typically `undefined`) if no connection was attempted.
 
 ```typescript
 async cancelAuthentication(serverName: string): Promise<boolean>
@@ -324,7 +324,7 @@ for (const serverName in templatesByServer) {
 
 #### `resources.read(serverName: string, uri: string)`
 
-Reads the content of a specific resource from a named server.
+Reads the content of a specific resource from a server.
 
 ```typescript
 async read(serverName: string, uri: string): Promise<ReadResourceResult>
@@ -342,7 +342,7 @@ console.log('Current weather:', content.contents[0].text)
 
 #### `resources.subscribe(serverName: string, uri: string)`
 
-Subscribes to updates for a specific resource on a named server.
+Subscribes to updates for a specific resource on a server.
 
 ```typescript
 async subscribe(serverName: string, uri: string): Promise<object>
@@ -356,7 +356,7 @@ await mcpClient.resources.subscribe('myWeatherServer', 'weather://current')
 
 #### `resources.unsubscribe(serverName: string, uri: string)`
 
-Unsubscribes from updates for a specific resource on a named server.
+Unsubscribes from updates for a specific resource on a server.
 
 ```typescript
 async unsubscribe(serverName: string, uri: string): Promise<object>
@@ -388,7 +388,7 @@ mcpClient.resources.onUpdated('myWeatherServer', params => {
 
 #### `resources.onListChanged(serverName: string, handler: () => void)`
 
-Sets a notification handler that will be called when the overall list of available resources changes on a specific server.
+Sets a notification handler that will be called when the list of available resources changes on a specific server.
 
 ```typescript
 async onListChanged(serverName: string, handler: () => void): Promise<void>
@@ -847,7 +847,7 @@ Give each server its own `MCPOAuthClientProvider` instance. A provider holds per
 
 ### Interactive browser authentication
 
-When a server rejects a connection because authorization is required, the client records a `'needs-auth'` state instead of failing outright. Calling `authenticate()` then completes the flow end to end: it starts a one-shot callback server on the provider's loopback redirect URL (falling back to the next sequential ports when it is in use), lets the SDK run discovery and dynamic client registration, delivers the authorization URL through `onRedirectToAuthorization` — open it in the user's browser — and finishes the token exchange once the browser returns the authorization code:
+When a server rejects a connection because authorization is required, the client records a `'needs-auth'` state instead of failing outright. Calling `authenticate()` completes the flow. It starts a one-shot callback server on the provider's loopback redirect URL, falling back to the next sequential ports when it's in use. The SDK then performs discovery and client registration at runtime. `onRedirectToAuthorization` receives the authorization URL so your application can open it in the user's browser. The token exchange finishes after the browser returns the authorization code:
 
 ```typescript
 import { MCPClient, MCPOAuthClientProvider } from '@mastra/mcp'
@@ -884,9 +884,9 @@ try {
 }
 ```
 
-Concurrent `authenticate()` calls for the same server join the pending flow; different servers authenticate independently. With valid stored tokens the call simply reconnects without opening a browser.
+Concurrent `authenticate()` calls for the same server join the pending flow. Different servers authenticate independently. With valid stored tokens the call reconnects without opening a browser.
 
-Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server, validates the OAuth `state` parameter, and resolves with the code. It creates a plain HTTP server, so it is only for local loopback redirects. Web applications that use an HTTPS redirect URL must host their own callback endpoint and drive the provider directly rather than using this helper:
+Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server, validates the OAuth `state` parameter, and resolves with the code. It creates a plain HTTP server, so it's only for local loopback redirects. Web applications that use an HTTPS redirect URL must host their own callback endpoint and drive the provider directly rather than using this helper:
 
 ```typescript
 import { createOAuthCallbackServer, getCallbackUrlCandidates } from '@mastra/mcp'
@@ -1139,9 +1139,9 @@ MCPClient handles server connections gracefully:
 2. Graceful server shutdown to prevent error messages during development
 3. Proper cleanup of resources when disconnecting
 
-## Using custom fetch for dynamic authentication
+## Using custom fetch for runtime-defined authentication
 
-For HTTP servers, you can provide a custom `fetch` function to handle dynamic authentication, request interception, or other custom behavior. This is particularly useful when you need to refresh tokens on each request or forward user credentials from the incoming request to the MCP server.
+For HTTP servers, you can provide a custom `fetch` function to handle runtime-defined authentication or request interception. It can also handle other custom behavior. This is particularly useful when you need to refresh tokens on each request or forward user credentials from the incoming request to the MCP server.
 
 The custom `fetch` function receives an optional third `requestContext` parameter, which provides access to request-scoped data (e.g., authentication cookies, bearer tokens) set by middleware or passed during agent/tool execution. The `requestContext` is `null` during the initial connection handshake.
 

package/.docs/reference/tools/mcp-server.md

@@ -101,20 +101,20 @@ A powerful feature of `MCPServer` is its ability to automatically expose your Ma
 
   - **Description**: The generated tool's description will be in the format: "Ask agent `<AgentName>` a question. Original agent instructions: `<agent description>`".
   - **Input**: The tool expects a single object argument with a `message` property (string): `{ message: "Your question for the agent" }`.
-  - **Execution**: When this tool is called, it invokes the `generate()` method of the corresponding agent, passing the provided `query`.
+  - **Execution**: When this tool is called, it invokes the corresponding agent's `generate()` method with the provided `query`.
   - **Output**: The direct result from the agent's `generate()` method is returned as the output of the tool.
 
-- **Name Collisions**: If an explicit tool defined in the `tools` configuration has the same name as an agent-derived tool (e.g., you have a tool named `ask_myAgentKey` and also an agent with the key `myAgentKey`), the _explicitly defined tool will take precedence_. The agent won't be converted into a tool in this conflicting case, and a warning will be logged.
+- **Name collisions.** If an explicit tool defined in the `tools` configuration has the same name as an agent-derived tool (e.g., a tool named `ask_myAgentKey` alongside an agent keyed as `myAgentKey`), the _explicitly defined tool will take precedence_. The agent won't be converted into a tool in this conflicting case, and a warning will be logged.
 
 This makes it straightforward to allow MCP clients to interact with your agents using natural language queries, like any other tool.
 
 ### Agent-to-Tool Conversion
 
-When you provide agents in the `agents` configuration property, `MCPServer` will automatically create a corresponding tool for each agent. The tool will be named `ask_<agentIdentifier>`, where `<agentIdentifier>` is the key you used in the `agents` object.
+When you provide agents in the `agents` configuration property, `MCPServer` will automatically create a corresponding tool for each agent. The tool will be `ask_<agentIdentifier>`, where `<agentIdentifier>` is the key you used in the `agents` object.
 
 The description for this generated tool will be: "Ask agent `<agent.name>` a question. Agent description: `<agent.description>`".
 
-**Important**: For an agent to be converted into a tool, it **must** have a non-empty `description` string property set in its configuration when it was instantiated (e.g., `new Agent({ id: 'my-agent', name: 'myAgent', description: 'This agent does X.', ... })`). If an agent is passed to `MCPServer` with a missing or empty `description`, an error will be thrown when the `MCPServer` is instantiated, and server setup will fail.
+For an agent to be converted into a tool, it **must** have a non-empty `description` string property set in its configuration when it was instantiated (e.g., `new Agent({ id: 'my-agent', name: 'myAgent', description: 'This agent does X.', ... })`). If an agent is passed to `MCPServer` with a missing or empty `description`, an error will be thrown when the `MCPServer` is instantiated, and server setup will fail.
 
 This allows you to quickly expose the generative capabilities of your agents through the MCP, enabling clients to "ask" your agents questions directly.
 
@@ -412,7 +412,7 @@ serve(async req => {
 >
 > This is still stateless: no `mcp-session-id` is required or persisted. It only enables notifications scoped to the current request (such as progress). The session-dependent features below remain unavailable.
 >
-> **Note:** The following MCP features require session state or persistent connections and **won't work** in serverless mode (including with `serverlessStreaming: true`):
+> The following MCP features require session state or persistent connections and **won't work** in serverless mode (including with `serverlessStreaming: true`):
 >
 > - **Elicitation** - Interactive user input requests during tool execution require session management to route responses back to the correct client
 > - **Resource subscriptions** - `resources/subscribe` and `resources/unsubscribe` need persistent connections to maintain subscription state
@@ -439,7 +439,7 @@ The `StreamableHTTPServerTransportOptions` object allows you to customize the be
 
 **serverless** (`boolean`): If true, runs in stateless mode without session management. Each request is handled independently with a fresh server instance. Essential for serverless environments (Cloudflare Workers, Supabase Edge Functions, Vercel Edge, etc.) where sessions cannot persist between invocations. Defaults to false.
 
-**serverlessStreaming** (`boolean`): If true, serverless requests use request-scoped SSE streaming instead of a buffered JSON response, allowing in-request notifications/progress to reach the client before the final result. Only takes effect together with serverless: true. Defaults to false (buffered JSON responses), which preserves backward-compatible behavior. This enables only request-scoped notifications such as progress; elicitation, subscriptions, and out-of-request notifications still require session state.
+**serverlessStreaming** (`boolean`): If true, serverless requests use request-scoped SSE streaming instead of a buffered JSON response, allowing in-request notifications/progress to reach the client before the final result. Only takes effect together with serverless: true. Defaults to false (buffered JSON responses), which preserves backward-compatible behavior. It enables only request-scoped notifications such as progress; elicitation, subscriptions, and out-of-request notifications still require session state.
 
 **sessionIdGenerator** (`(() => string) | undefined`): A function that generates a unique session ID. This should be a cryptographically secure, globally unique string. Return undefined to disable session management.
 
@@ -459,7 +459,7 @@ async close(): Promise<void>
 
 ### `getServerInfo()`
 
-This method gives you a look at the server's basic information.
+The method returns the server's basic information.
 
 ```typescript
 getServerInfo(): ServerInfo
@@ -467,7 +467,7 @@ getServerInfo(): ServerInfo
 
 ### `getServerDetail()`
 
-This method gives you a detailed look at the server's information.
+The method returns details about the server's information.
 
 ```typescript
 getServerDetail(): ServerDetail
@@ -475,7 +475,7 @@ getServerDetail(): ServerDetail
 
 ### `getToolListInfo()`
 
-This method gives you a look at the tools that were set up when you created the server. It's a read-only list, useful for debugging purposes.
+The method returns the tools that were set up when you created the server. It's a read-only list, useful for debugging purposes.
 
 ```typescript
 getToolListInfo(): ToolListInfo
@@ -483,7 +483,7 @@ getToolListInfo(): ToolListInfo
 
 ### `getToolInfo()`
 
-This method gives you detailed information about a specific tool.
+The method returns details about a specific tool.
 
 ```typescript
 getToolInfo(toolName: string): ToolInfo
@@ -565,7 +565,7 @@ Resources are identified by unique URIs (e.g., `file:///home/user/documents/repo
 Clients can discover resources through:
 
 1. **Direct resources**: Servers expose a list of concrete resources via a `resources/list` endpoint.
-2. **Resource templates**: For dynamic resources, servers can expose URI templates (RFC 6570) that clients use to construct resource URIs.
+2. **Resource templates**: For runtime-defined resources, servers can expose URI templates (RFC 6570) that clients use to construct resource URIs.
 
 To read a resource, clients make a `resources/read` request with the URI. Servers can also notify clients about changes to the resource list (`notifications/resources/list_changed`) or updates to specific resource content (`notifications/resources/updated`) if a client has subscribed to that resource.
 
@@ -659,7 +659,7 @@ await serverWithResources.resources.notifyUpdated({ uri: 'file://data.txt' })
 
 #### `server.resources.notifyListChanged()`
 
-Call this method when the overall list of available resources has changed (e.g., a resource was added or removed). This will send a `notifications/resources/list_changed` message to clients, prompting them to re-fetch the list of resources.
+Call this method when the list of available resources has changed (e.g., a resource was added or removed). This will send a `notifications/resources/list_changed` message to clients, prompting them to re-fetch the list of resources.
 
 ```typescript
 async server.resources.notifyListChanged(): Promise<void>
@@ -676,9 +676,9 @@ await serverWithResources.resources.notifyListChanged()
 
 ### What are MCP Prompts?
 
-Prompts are reusable templates or workflows that MCP servers expose to clients. They can accept arguments, include resource context, support versioning, and be used to standardize LLM interactions.
+Prompts are reusable templates or workflows that MCP servers expose to clients. They can accept arguments and include resource context. They also support versioning and standardize LLM interactions.
 
-Prompts are identified by a unique name (and optional version) and can be dynamic or static.
+Prompts are identified by a unique name (and optional version) and can be runtime-defined or static.
 
 ### `MCPServerPrompts` Type
 
@@ -773,7 +773,7 @@ If the available prompts change, your server can notify connected clients:
 
 #### `server.prompts.notifyListChanged()`
 
-Call this method when the overall list of available prompts has changed (e.g., a prompt was added or removed). This will send a `notifications/prompts/list_changed` message to clients, prompting them to re-fetch the list of prompts.
+Call this method when the list of available prompts has changed (e.g., a prompt was added or removed). This will send a `notifications/prompts/list_changed` message to clients, prompting them to re-fetch the list of prompts.
 
 ```typescript
 await serverWithPrompts.prompts.notifyListChanged()
@@ -793,7 +793,7 @@ await serverWithPrompts.prompts.notifyListChanged()
 
 Tools are usually provided when constructing the `MCPServer`, but you can also add or remove tools while the server is running. The server exposes these operations through the `toolActions` property. When the tool list changes, connected clients receive a `notifications/tools/list_changed` message prompting them to re-fetch the tool list.
 
-The property is named `toolActions` because `tools()` is the method that returns the registered tool registry.
+The property is `toolActions` because `tools()` is the method that returns the registered tool registry.
 
 ### `toolActions.add(tools)`
 
@@ -821,7 +821,7 @@ await server.toolActions.add({ searchTool })
 
 ### `toolActions.remove(toolIds)`
 
-Removes tools from the running server by tool ID and notifies connected clients. Unknown tool IDs are ignored. If no tools were removed, no notification is sent.
+Removes tools from the running server by tool ID and notifies connected clients. Unknown tool IDs are ignored. A notification is sent only when at least one tool is removed.
 
 ```typescript
 async server.toolActions.remove(toolIds: string[]): Promise<void>
@@ -847,7 +847,7 @@ When the server is registered with a Mastra instance, `toolActions.add()` and `t
 
 ## Logging
 
-MCP servers can send structured log messages to clients using `notifications/message`. Clients control verbosity by sending a `logging/setLevel` request; the server drops messages below the requested minimum level (following RFC 5424 severity ordering). The level is tracked per session, so different clients can request different verbosity.
+MCP servers can send structured log messages to clients using `notifications/message`. Clients control verbosity by sending a `logging/setLevel` request. The server drops messages below the requested minimum level (following RFC 5424 severity ordering). The level is tracked per session, so different clients can request different verbosity.
 
 ### `sendLoggingMessage()`
 
@@ -937,7 +937,7 @@ The example at the beginning of this page also demonstrates how to instantiate `
 
 ### What's Elicitation?
 
-Elicitation is a feature in the Model Context Protocol (MCP) that allows servers to request structured information from users. This enables interactive workflows where servers can collect additional data dynamically.
+Elicitation is a feature in the Model Context Protocol (MCP) that allows servers to request structured information from users. It supports interactive workflows where servers can collect additional data at runtime.
 
 The `MCPServer` class automatically includes elicitation capabilities. Tools receive a `context.mcp` object in their `execute` function that includes an `elicitation.sendRequest()` method for requesting user input.
 
@@ -1126,7 +1126,7 @@ execute: async (inputData, context) => {
 }
 ```
 
-Note that elicitation is **session-aware** when using HTTP-based transports (SSE or HTTP). This means that when multiple clients are connected to the same server, elicitation requests are routed to the correct client session that initiated the tool execution.
+Elicitation is **session-aware** when using HTTP-based transports (SSE or HTTP). When multiple clients are connected to the same server, elicitation requests are routed to the client session that initiated the tool execution.
 
 The `ElicitResult` type:
 

package/.docs/reference/tools/submit-plan-tool.md

@@ -4,7 +4,7 @@
 
 A built-in, agent-agnostic tool that submits an implementation plan for user review. The agent writes a plan to a markdown file and passes the file path to this tool. The tool suspends the run until the user approves or rejects the plan.
 
-The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend({ path })`, which makes the agent emit a `tool-call-suspended` event. The host reads the plan file, presents it to the user, and resumes with an approval or rejection.
+The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend({ path })`, which makes the agent emit a `tool-call-suspended` event. The host reads the plan file and presents it to the user. It then resumes with an approval or rejection.
 
 When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the file path.
 

package/.docs/reference/tools/tavily.md

@@ -2,7 +2,7 @@
 
 # Tavily tools
 
-The `@mastra/tavily` package wraps the [Tavily](https://app.tavily.com) API as Mastra-compatible tools. It exposes factory functions for search, extract, crawl, and map — each returning a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.
+The `@mastra/tavily` package wraps the [Tavily](https://app.tavily.com) API as Mastra-compatible tools. It exposes factory functions for search, extract, crawl, and map. Each function returns a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.
 
 ## Installation
 

package/.docs/reference/tools/vector-query-tool.md

@@ -2,7 +2,7 @@
 
 # createVectorQueryTool()
 
-The `createVectorQueryTool()` function creates a tool for semantic search over vector stores. It supports filtering, reranking, database-specific configurations, and integrates with various vector store backends.
+The `createVectorQueryTool()` function creates a tool for semantic search over vector stores. It supports filtering, reranking, database-specific configurations, and integrates with vector store backends.
 
 ## Basic usage
 
@@ -69,7 +69,7 @@ const queryTool = createVectorQueryTool({
 
 **databaseConfig.chroma.whereDocument** (`Record<string, any>`): Document content filtering conditions
 
-**providerOptions** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
+**providerOptions** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
 
 **vectorStore** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, vectorStoreName becomes optional.
 
@@ -182,7 +182,7 @@ This example shows how to customize the tool description for a specific use case
 
 ## Database-specific configuration examples
 
-The `databaseConfig` parameter allows you to leverage unique features and optimizations specific to each vector database. These configurations are automatically applied during query execution.
+The `databaseConfig` parameter allows you to use features and optimizations specific to each vector database. These configurations are automatically applied during query execution.
 
 **Pinecone**:
 
@@ -475,7 +475,7 @@ const result = await vectorQueryTool.execute(
 )
 ```
 
-This pattern is similar to how `Agent.memory` supports dynamic configuration and enables:
+This pattern is similar to how `Agent.memory` supports runtime-defined configuration and enables:
 
 - **Schema isolation**: Each tenant's data in separate PostgreSQL schemas
 - **Database isolation**: Route to different database instances per tenant

package/.docs/reference/vectors/astra.md

@@ -2,7 +2,7 @@
 
 # Astra vector store
 
-The AstraVector class provides vector search using [DataStax Astra DB](https://www.datastax.com/products/datastax-astra), a cloud-native, serverless database built on Apache Cassandra. It provides vector search capabilities with enterprise-grade scalability and high availability.
+The AstraVector class provides vector search using [DataStax Astra DB](https://www.datastax.com/products/datastax-astra), a cloud-native, serverless database built on Apache Cassandra. It provides vector search capabilities with enterprise-grade capacity and high availability.
 
 ## Constructor options
 

package/.docs/reference/vectors/chroma.md

@@ -8,7 +8,7 @@ The ChromaVector class provides vector search using [Chroma](https://docs.trychr
 >
 > **Chroma Cloud**
 >
-> Chroma Cloud powers serverless vector and full-text search. It's extremely fast, cost-effective, scalable and painless. Create a DB and try it out in under 30 seconds with $5 of free credits.
+> Chroma Cloud powers serverless vector and full-text search. It's extremely fast, cost-effective, high-capacity, and painless. Create a DB and try it out in under 30 seconds with $5 of free credits.
 >
 > [Get started with Chroma Cloud](https://trychroma.com/signup)
 
@@ -197,7 +197,7 @@ await vectorStore.updateVector({
 
 ### `deleteVectors()`
 
-Delete multiple vectors by IDs or by metadata filter. This method enables bulk deletion and source-based vector management. Either `ids` or `filter` must be provided, but not both.
+Delete multiple vectors by IDs or by metadata filter. The method supports bulk deletion and source-based vector management. Either `ids` or `filter` must be provided, but not both.
 
 **indexName** (`string`): Name of the index containing the vectors to delete
 

package/.docs/reference/vectors/convex.md

@@ -351,7 +351,7 @@ interface QueryResult {
 
 ## Metadata filtering
 
-`ConvexVector` supports metadata filtering with various operators. These filters are applied by the adapter after vectors are loaded from Convex.
+`ConvexVector` supports metadata filtering with operators. These filters are applied by the adapter after vectors are loaded from Convex.
 
 ```typescript
 // Simple equality
@@ -415,7 +415,7 @@ Vector similarity search is performed with cosine similarity in the Mastra adapt
 - Filters must target fields listed in the Convex vector index `filterFields`.
 - Use one dedicated table per Mastra vector index to avoid cross-index results.
 
-Use an external vector database when you need dynamic index creation at runtime, metadata-only queries, complex filter operators, filter-based bulk updates or deletes, or result limits above Convex's native vector search cap.
+Use an external vector database when you need runtime-defined index creation at runtime, metadata-only queries, complex filter operators, filter-based bulk updates or deletes, or result limits above Convex's native vector search cap.
 
 ## Related
 

package/.docs/reference/vectors/couchbase.md

@@ -75,7 +75,7 @@ const store = new CouchbaseVector({
 
 Creates a new vector index in Couchbase.
 
-> **Note:** Index creation is asynchronous. After calling `createIndex`, allow time (typically 1–5 seconds for small datasets, longer for large ones) before querying. For production, implement polling to check index status rather than using fixed delays.
+> **Note:** Index creation is asynchronous. After calling `createIndex`, allow time (typically 1 to 5 seconds for small datasets, longer for large ones) before querying. For production, implement polling to check index status rather than using fixed delays.
 
 **indexName** (`string`): Name of the index to create
 
@@ -145,7 +145,7 @@ Returns: `Promise<string[]>`
 
 ### `updateVector()`
 
-Updates a specific vector entry by its ID with new vector data and/or metadata. **Note:** Filter-based updates aren't yet implemented for Couchbase.
+Updates a specific vector entry by its ID with new vector data and/or metadata. Filter-based updates aren't yet implemented for Couchbase.
 
 **indexName** (`string`): Name of the index containing the vector
 
@@ -163,7 +163,7 @@ Deletes a single vector by its ID from the index.
 
 ### `deleteVectors()`
 
-Deletes multiple vectors by their IDs. **Note:** Filter-based deletion isn't yet implemented for Couchbase.
+Deletes multiple vectors by their IDs. Filter-based deletion isn't yet implemented for Couchbase.
 
 **indexName** (`string`): Name of the index containing the vectors to delete
 
@@ -221,7 +221,7 @@ try {
 
 - Index creation delays may impact immediate querying after creation.
 - No hard enforcement of vector dimension at ingest time (dimension mismatches will error at query time).
-- Vector insertion and index updates are eventually consistent; strong consistency isn't guaranteed immediately after writes.
+- Vector insertion and index updates are eventually consistent. Strong consistency isn't guaranteed immediately after writes.
 
 ## Related
 

package/.docs/reference/vectors/libsql.md

@@ -85,7 +85,7 @@ const results = await store.query({
 
 ### `createIndex()`
 
-Creates a new vector collection. The index name must start with a letter or underscore and can only contain letters, numbers, and underscores. The dimension must be a positive integer.
+Creates a new vector collection. The index name must start with a letter or underscore and can only contain letters, numbers, and underscore characters. The dimension must be a positive integer.
 
 **indexName** (`string`): Name of the index to create
 

package/.docs/reference/vectors/mongodb.md

@@ -559,7 +559,7 @@ export const mongodbVoyageAgent = new Agent({
 })
 ```
 
-For comprehensive VoyageAI embedding examples including specialized models, multimodal embeddings, and retrieval optimization, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings).
+For detailed VoyageAI embedding examples including specialized models, multimodal embeddings, and retrieval optimization, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings).
 
 ## Related
 

package/.docs/reference/vectors/pg.md

@@ -2,7 +2,7 @@
 
 # PG vector store
 
-The PgVector class provides vector search using [PostgreSQL](https://www.postgresql.org/) with [pgvector](https://github.com/pgvector/pgvector) extension. It provides robust vector similarity search capabilities within your existing PostgreSQL database.
+The PgVector class provides vector search using [PostgreSQL](https://www.postgresql.org/) with [pgvector](https://github.com/pgvector/pgvector) extension. It provides reliable vector similarity search capabilities within your existing PostgreSQL database.
 
 ## Constructor options
 
@@ -110,13 +110,13 @@ const vectorStore = new PgVector({
 
 #### Memory Requirements
 
-HNSW indexes require significant shared memory during construction. For 100K vectors:
+HNSW indexes require substantial shared memory during construction. For 100K vectors:
 
 - Small dimensions (64d): \~60MB with default settings
 - Medium dimensions (256d): \~180MB with default settings
 - Large dimensions (384d+): \~250MB+ with default settings
 
-Higher M values or efConstruction values will increase memory requirements significantly. Adjust your system's shared memory limits if needed.
+Higher M values or efConstruction values will increase memory requirements substantially. Adjust your system's shared memory limits if needed.
 
 ### `upsert()`
 
@@ -340,7 +340,7 @@ The system automatically detects configuration changes and only rebuilds indexes
 - Regularly evaluate your index configuration to ensure optimal performance.
 - Adjust parameters like `lists` and `m` based on dataset size and query requirements.
 - **Monitor index performance** using `describeIndex()` to track usage
-- Rebuild indexes periodically to maintain efficiency, especially after significant data changes
+- Rebuild indexes periodically to maintain efficiency, especially after substantial data changes
 
 ## Direct pool access
 

package/.docs/reference/vectors/qdrant.md

@@ -86,7 +86,7 @@ await store.upsert({
 
 #### Named Vectors
 
-Qdrant supports [named vectors](https://qdrant.tech/documentation/concepts/vectors/#named-vectors), allowing multiple vector fields per collection. Use the `using` parameter to specify which named vector to query against:
+Qdrant supports [multiple vectors per collection](https://qdrant.tech/documentation/concepts/vectors/#named-vectors), with a name assigned to each vector field. Use the `using` parameter to select the vector field to query:
 
 ```typescript
 const results = await store.query({
@@ -131,7 +131,7 @@ Update a single vector by ID or by metadata filter. Either `id` or `filter` must
 
 **update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
 
-Updates a vector and/or its metadata in the specified index. If both vector and metadata are provided, both will be updated. If only one is provided, only that will be updated.
+Updates a vector and/or its metadata in the specified index. If both vector and metadata are provided, both will be updated. Providing either value updates that value alone.
 
 ### `deleteVector()`
 

package/.docs/reference/vectors/s3vectors.md

@@ -205,8 +205,8 @@ S3 Vectors supports a strict subset of operators and value types. The Mastra fil
 
 - **Canonicalizes implicit AND**: `{a:1,b:2}` → `{ $and: [{a:1},{b:2}] }`.
 - **Normalizes Date values** to epoch ms for numeric comparisons and array elements.
-- **Disallows Date** in equality positions (`field: value` or `$eq/$ne`); equality values must be **string | number | boolean**.
-- **Rejects** null/undefined for equality; **array equality** isn't supported (use `$in`/`$nin`).
+- **Disallows Date** in equality positions (`field: value` or `$eq/$ne`). Equality values must be **string | number | boolean**.
+- **Rejects** null/undefined for equality. **array equality** isn't supported (use `$in`/`$nin`).
 - Only **`$and` / `$or`** are allowed as top-level logical operators.
 - Logical operators must contain **field conditions** (not direct operators).
 
@@ -268,10 +268,10 @@ Typical environment variables when wiring your app:
 
 ## Best practices
 
-- Choose the metric (`cosine` or `euclidean`) to match your embedding model; `dotproduct` isn't supported.
+- Choose the metric (`cosine` or `euclidean`) to match your embedding model. `dotproduct` isn't supported.
 - Keep **filterable** metadata small and structured (string/number/boolean). Store large text (e.g., `content`) as **non-filterable**.
 - Use **dotted paths** for nested metadata and explicit `$and`/`$or` for complex logic.
-- Avoid calling `describeIndex()` on hot paths—`count` is computed with paginated `ListVectors` (**O(n)**).
+- Avoid calling `describeIndex()` on hot paths. `count` is computed with paginated `ListVectors` (**O(n)**).
 - Use `includeVector: true` only when you need raw vectors.
 
 ## Related