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

package/.docs/reference/storage/retention.md

@@ -4,9 +4,9 @@
 
 Storage grows without bound by default. Retention is an opt-in, age-based cleanup system: you declare per-table `maxAge` policies in the `retention` config, then call `storage.prune()` to delete rows older than their configured age. Anything you don't configure is kept forever, so there is no behavior change until you opt in.
 
-`prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk — on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
+`prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk: on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
 
-Retention covers **growth tables** only — tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they're not valid retention keys.
+Retention covers **growth tables** only: tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they're not valid retention keys.
 
 The reference implementations are [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). Other adapters keep rows forever until they implement retention.
 
@@ -31,7 +31,7 @@ const storage = new LibSQLStore({
   },
 })
 
-// Wire this to your own cron/scheduler — Mastra never runs it for you.
+// Wire this to your own cron/scheduler: Mastra never runs it for you.
 const results = await storage.prune()
 ```
 
@@ -65,35 +65,35 @@ Set the `retention` field on the store config.
 
 ### Retention-eligible tables
 
-Each domain declares which of its tables can be age-pruned and which timestamp column anchors the comparison. The anchor is chosen so `maxAge` means what you'd expect for that data: creation time for append-only logs, last activity for live state, and completion time for jobs and runs (so in-flight work is never pruned).
-
-| Domain            | Table key          | Anchor column    | `maxAge` measures                                                 |
-| ----------------- | ------------------ | ---------------- | ----------------------------------------------------------------- |
-| `memory`          | `threads`          | `createdAt`      | Thread age                                                        |
-| `memory`          | `messages`         | `createdAt`      | Message age                                                       |
-| `memory`          | `resources`        | `createdAt`      | Resource age                                                      |
-| `threadState`     | `threadState`      | `updatedAt`      | Inactivity — state for still-active threads survives              |
-| `observability`   | `spans`            | `startedAt`      | Span age                                                          |
-| `observability`   | `metrics`          | `timestamp`      | Metric event age (v-next only)                                    |
-| `observability`   | `logs`             | `timestamp`      | Log event age (v-next only)                                       |
-| `observability`   | `scores`           | `timestamp`      | Score event age (v-next only)                                     |
-| `observability`   | `feedback`         | `timestamp`      | Feedback event age (v-next only)                                  |
-| `scores`          | `scorers`          | `createdAt`      | Score record age                                                  |
-| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity — suspended or long-running workflows survive          |
-| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion — in-flight tasks (`NULL`) are never pruned |
-| `experiments`     | `experiments`      | `completedAt`    | Time since completion — running experiments are never pruned      |
-| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                  |
-| `harness`         | `sessions`         | `createdAt`      | Session record age                                                |
-| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                                |
+Each domain declares which of its tables can be age-pruned and which timestamp column anchors the comparison. The anchor is chosen so `maxAge` means what you'd expect for that data. Append-only logs use creation time, and live state uses last activity. Jobs and runs use completion time, so in-flight work is never pruned.
+
+| Domain            | Table key          | Anchor column    | `maxAge` measures                                                |
+| ----------------- | ------------------ | ---------------- | ---------------------------------------------------------------- |
+| `memory`          | `threads`          | `createdAt`      | Thread age                                                       |
+| `memory`          | `messages`         | `createdAt`      | Message age                                                      |
+| `memory`          | `resources`        | `createdAt`      | Resource age                                                     |
+| `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives              |
+| `observability`   | `spans`            | `startedAt`      | Span age                                                         |
+| `observability`   | `metrics`          | `timestamp`      | Metric event age (v-next only)                                   |
+| `observability`   | `logs`             | `timestamp`      | Log event age (v-next only)                                      |
+| `observability`   | `scores`           | `timestamp`      | Score event age (v-next only)                                    |
+| `observability`   | `feedback`         | `timestamp`      | Feedback event age (v-next only)                                 |
+| `scores`          | `scorers`          | `createdAt`      | Score record age                                                 |
+| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive          |
+| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned |
+| `experiments`     | `experiments`      | `completedAt`    | Time since completion, running experiments are never pruned      |
+| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                 |
+| `harness`         | `sessions`         | `createdAt`      | Session record age                                               |
+| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                               |
 
 > **Note:**
 >
 > - The memory `observational_memory` table has no timestamp anchor, so it can't be age-pruned and isn't a valid retention key.
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
-> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire) — schedule definitions are config and aren't pruned.
+> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
 > - LibSQL supports all domains above; PostgreSQL and MongoDB support all except `threadState` and `harness`, which they don't implement.
-> - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows — effective granularity is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
+> - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows: effective level of detail is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
 
 ## Methods
 
@@ -103,11 +103,11 @@ Each domain declares which of its tables can be age-pruned and which timestamp c
 
 Deletes rows older than their configured `maxAge` across every domain that has a policy in `retention`. Returns one `PruneResult` per table touched. With no `retention` configured it's a no-op returning `[]`.
 
-`prune()` is designed to be safe on tables with millions of rows. It deletes in bounded, batched chunks — each batch is its own transaction — so it never takes a long lock or bloats the transaction log. It never runs a `VACUUM`.
+`prune()` is designed to be safe on tables with millions of rows. It deletes in bounded, batched chunks (each batch is its own transaction) so it never takes a long lock or bloats the transaction log. It never runs a `VACUUM`.
 
-Pass `options.retention` to replace the configured policies for that call only — for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
+Pass `options.retention` to replace the configured policies for that call only: for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
 
-Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy — never at `init()` — so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build; subsequent prunes reuse the index.
+Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy (never at `init()`) so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build. Subsequent prunes reuse the index.
 
 ```typescript
 const results = await storage.prune({
@@ -156,7 +156,7 @@ interface PruneResult {
 
 ## Running prune on a schedule
 
-`prune()` has no built-in scheduler — you decide when it runs. Because it's bounded, a single call may not delete everything. When any result has `done: false`, eligible rows remain and you call again on the next tick. This keeps each invocation short and lets a large backlog drain over several runs.
+`prune()` has no built-in scheduler: you decide when it runs. Because it's bounded, a single call may not delete everything. When any result has `done: false`, eligible rows remain and you call again on the next tick. This keeps each invocation short and lets a large backlog drain over several runs.
 
 ```typescript
 // Runs on your own cron (node-cron, a workflow schedule, an external job, etc.).
@@ -173,7 +173,7 @@ async function retentionTick() {
 }
 ```
 
-You can also cancel a long-running prune with an `AbortSignal` — the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
+You can also cancel a long-running prune with an `AbortSignal`: the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
 
 ## MongoDB TTL indexes (alternative to prune)
 
@@ -192,7 +192,7 @@ MongoDB offers native [TTL (Time-To-Live) indexes](https://www.mongodb.com/docs/
 > - You need resumable, cancellable cleanup operations
 > - You're using composite storage with multiple databases
 >
-> Both approaches are valid. TTL is simpler; `prune()` gives more control.
+> Both approaches are valid. TTL is simpler. `prune()` gives more control.
 
 ### Setting up TTL indexes on MongoDB
 
@@ -232,9 +232,9 @@ const storage = new MongoDBStore({
 
 ## Reclaiming disk
 
-`prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist and are reused by future writes, so the file stops growing — for most users this alone solves the unbounded-growth problem.
+`prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist and are reused by future writes, so the file stops growing: for most users this alone solves the unbounded-growth problem.
 
-Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself, in a maintenance window — a full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically; a manual `VACUUM FULL` is only needed if you must return disk to the OS.
+Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself in a maintenance window. A full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically; a manual `VACUUM FULL` is only needed if you must return disk to the OS.
 
 For MongoDB, deleted documents are reused by future insertions. To reclaim disk space, run [`db.runCommand({ compact: "collection_name" })`](https://www.mongodb.com/docs/manual/reference/command/compact/) during a maintenance window.
 

package/.docs/reference/storage/spanner.md

@@ -2,7 +2,7 @@
 
 # Google Cloud Spanner storage
 
-The Google Cloud Spanner storage implementation provides a horizontally scalable, strongly consistent storage backend for Mastra. It targets the GoogleSQL dialect of Cloud Spanner.
+The Google Cloud Spanner storage implementation provides a horizontally high-capacity, strongly consistent storage backend for Mastra. It targets the GoogleSQL dialect of Cloud Spanner.
 
 ## Installation
 
@@ -133,14 +133,14 @@ The storage adapter creates the following tables, all using the GoogleSQL dialec
 
 Tables are created with `STRING(MAX)` for text and JSON payloads, `INT64`, `FLOAT64`, `BOOL`, and `TIMESTAMP`.
 
-Two tables also carry Spanner-specific `STORED` generated columns that the adapter populates from JSON payloads so common filters can use a regular secondary index instead of a `JSON_VALUE` scan:
+The following tables carry Spanner-specific `STORED` generated columns that the adapter populates from JSON payloads so common filters can use a regular secondary index instead of a `JSON_VALUE` scan:
 
-- `mastra_workflow_snapshot.snapshotStatus` — extracts `$.status` from `snapshot`; backs `listWorkflowRuns({ status })`.
-- `mastra_schedules.target_workflow_id` — extracts `$.workflowId` from `target`; backs `listSchedules({ workflowId })`.
+- `mastra_workflow_snapshot.snapshotStatus`: Extracts `$.status` from `snapshot`. Backs `listWorkflowRuns({ status })`.
+- `mastra_schedules.target_workflow_id`: Extracts `$.workflowId` from `target`. Backs `listSchedules({ workflowId })`.
 
 Both are added via `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` during `init()` and skipped under `initMode: 'validate'` (where the schema is owned externally). When the column is absent, the adapter falls back to a `JSON_VALUE` filter at runtime.
 
-The adapter doesn't create or use named schemas; use a dedicated database for isolation.
+The adapter doesn't create or use schemas. Use a dedicated database for isolation.
 
 ### Initialization
 
@@ -184,11 +184,11 @@ const thread = await memory?.getThreadById({ threadId: '...' })
 A few behaviors differ from other relational adapters:
 
 - Upserts use `INSERT OR UPDATE`. Spanner doesn't provide a `RETURNING` clause for upserts, so callers needing the post-write state must read it back.
-- No `TRUNCATE` exists; `dangerouslyClearAll()` issues `DELETE WHERE TRUE`.
+- No `TRUNCATE` exists. `dangerouslyClearAll()` issues `DELETE WHERE TRUE`.
 - Identifiers are quoted with backticks.
 - DDL is applied through `database.updateSchema(...)`, which is asynchronous (long-running operation).
 - `NULLS FIRST/LAST` isn't supported. Ordering with NULL handling is emulated through an `IS NULL` ordering key.
-- JSON containment isn't supported natively. `listTraces` `metadata` and `scope` filters compile to per-key `JSON_VALUE(...) = @v` equality checks, and `tags` filters compile to `EXISTS` over `JSON_QUERY_ARRAY(...)`. This differs from Postgres' `@>` containment operator (which can match nested structure in a single index scan) — most one-shot lookups still work but deeply nested structural matches aren't expressible.
+- JSON containment isn't supported natively. `listTraces` `metadata` and `scope` filters compile to per-key `JSON_VALUE(...) = @v` equality checks, and `tags` filters compile to `EXISTS` over `JSON_QUERY_ARRAY(...)`. This differs from Postgres' `@>` containment operator (which can match nested structure in a single index scan): most one-shot lookups still work but deeply nested structural matches aren't expressible.
 
 ### Direct database access
 
@@ -217,4 +217,4 @@ gcloud spanner instances create test-instance --config=emulator-config --nodes=1
 gcloud spanner databases create test-db --instance=test-instance
 ```
 
-Then connect with the same env var set in your Node.js process; the `@google-cloud/spanner` client detects the emulator automatically.
+Then connect with the same env var set in your Node.js process. The `@google-cloud/spanner` client detects the emulator automatically.

package/.docs/reference/streaming/ChunkType.md

@@ -522,9 +522,9 @@ Emitted when the task throws or times out. Triggers a continuation turn when con
 
 ### background-task-suspended
 
-Emitted when a tool calls `suspend()` from inside its background execution. Pauses the task's workflow run with its snapshot persisted; resume with `mastra.backgroundTaskManager.resume(taskId, resumeData)`.
+Emitted when a tool calls `suspend()` from inside its background execution. Pauses the task's workflow run with its snapshot persisted. Resume with `mastra.backgroundTaskManager.resume(taskId, resumeData)`.
 
-When consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle), this chunk drops the task from the loop's wait set without queuing a continuation — the agent's response ends, and the resumed task's eventual completion injects into the message list for the next user turn.
+When consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle), this chunk drops the task from the loop's wait set without queuing a continuation. The agent's response ends, and the resumed task's eventual completion injects into the message list for the next user turn.
 
 **type** (`"background-task-suspended"`): Chunk type identifier
 

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

@@ -2,7 +2,7 @@
 
 # MastraModelOutput
 
-The `MastraModelOutput` class is returned by [.stream()](https://mastra.ai/reference/streaming/agents/stream) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and comprehensive usage tracking.
+The `MastraModelOutput` class is returned by [.stream()](https://mastra.ai/reference/streaming/agents/stream) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and detailed usage tracking.
 
 ```typescript
 // MastraModelOutput is returned by agent.stream()

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

@@ -2,7 +2,7 @@
 
 # Agent.stream()
 
-The `.stream()` method enables real-time streaming of responses from an agent with enhanced capabilities and format flexibility. This method accepts messages and optional streaming options, providing a next-generation streaming experience with support for both Mastra's native format and AI SDK v5+ compatibility.
+The `.stream()` method enables real-time streaming of responses from an agent with enhanced capabilities and format flexibility. This method accepts messages and optional streaming options, providing a current streaming experience with support for both Mastra's native format and AI SDK v5+ compatibility.
 
 ## Usage example
 

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: