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

package/.docs/docs/agents/using-tools.md

@@ -65,6 +65,31 @@ export const weatherAgent = new Agent({
 })
 ```
 
+## Use provider web search
+
+Import `webSearchTool` from `@mastra/core/tools` when you want the model provider to run its native web search tool. The tool has no local `execute` function. Mastra resolves it at run time from the active model, then passes the provider-managed tool to the model.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { webSearchTool } from '@mastra/core/tools'
+
+export const researchAgent = new Agent({
+  id: 'research-agent',
+  name: 'Research Agent',
+  instructions: `
+    You are a helpful research assistant.
+    Use web search when you need current information.`,
+  model: 'openai/gpt-5.5',
+  tools: {
+    webSearch: webSearchTool,
+  },
+})
+```
+
+`webSearchTool` supports OpenAI, Anthropic, Google Gemini, and xAI models. If Mastra can't infer one of those providers from the active model, the agent run fails with a `MastraError`.
+
+Only the `webSearchTool` value triggers provider web search. A custom tool named `webSearch` or `web_search` stays unchanged.
+
 ## Define schemas
 
 You can define the tool's `inputSchema` and `outputSchema` with any library that supports [Standard JSON Schema](https://standardschema.dev/json-schema). This includes libraries like [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and [ArkType](https://arktype.io/).

package/.docs/guides/build-your-ui/ai-sdk-ui.md

@@ -44,7 +44,7 @@ You're now ready to follow the integration guides and recipes below!
 
 ## Integration guides
 
-Typically, you'll set up API routes that stream Mastra content in AI SDK-compatible format, and then use those routes in AI SDK UI hooks like `useChat()`. Below you'll find two main approaches to achieve this:
+Typically, you'll set up API routes that stream Mastra content in AI SDK-compatible format, and then use those routes in AI SDK UI hooks like `useChat()`. Choose one of these approaches:
 
 - [Mastra's server](#mastras-server)
 - [Framework-agnostic](#framework-agnostic)
@@ -298,7 +298,7 @@ export default function Page() {
 }
 ```
 
-Below are two approaches to implementing the backend:
+Choose a backend implementation:
 
 **Mastra Server**:
 
@@ -380,7 +380,7 @@ export async function POST(req: Request) {
 
 ## Custom UI
 
-Custom UI (also known as Generative UI) allows you to render custom React components based on data streamed from Mastra. Instead of displaying raw text or JSON, you can create visual components for tool outputs, workflow progress, agent network execution, and custom events.
+Custom UI (also known as Generative UI) allows you to render custom React components based on data streamed from Mastra. Instead of displaying raw text or JSON, you can create visual components for tool outputs and workflow progress, including agent network execution and custom events.
 
 Use Custom UI when you want to:
 
@@ -990,7 +990,7 @@ export function ChatAdditional() {
 }
 ```
 
-Two examples on how to implement the backend portion of it.
+Implement the backend with either of these examples.
 
 **Mastra Server**:
 
@@ -1545,7 +1545,7 @@ For a complete implementation, see the [workflow-agent-text-stream example](http
 
 ### Multi-stage progress with branching workflows
 
-For workflows with conditional branching (e.g., express vs standard shipping), you can track progress across different branches by including a identifier in your custom events.
+For workflows with conditional branching (e.g., express vs standard delivery), you can track progress across different branches by including an identifier in your custom events.
 
 The UI Dojo example uses a `stage` field in the event data to identify which branch is executing (e.g., `"validation"`, `"standard-processing"`, `"express-processing"`). The frontend groups events by this field to show a pipeline-style progress UI.
 

package/.docs/guides/build-your-ui/copilotkit/generative-ui.md

@@ -2,23 +2,23 @@
 
 # CopilotKit generative UI
 
-Generative UI is the family of UI paradigms enabled by agents and useful for interacting with them. CopilotKit organizes these along a single axis, the **generative UI spectrum**, which runs from author-controlled (you decide every pixel) to agent-invented (the agent owns the rendered surface). Where you sit on the axis is a trade-off between predictability and breadth.
+Generative UI describes interfaces that agents help create and that users can interact with. CopilotKit organizes these interfaces along a single axis, the **generative UI spectrum**, which runs from author-controlled (you decide every pixel) to agent-invented (the agent owns the rendered surface). Your position on the axis is a trade-off between predictability and breadth.
 
 The spectrum has three tiers:
 
 | Tier            | Who controls the surface                                                                   | Primitives                                                           |
 | --------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| **Controlled**  | You wrote the component; the agent picks which one and what data to pass.                  | Tool call rendering, state rendering, reasoning, components as tools |
-| **Declarative** | The agent emits a structured spec; the frontend composes it from a catalog you registered. | A2UI (fixed schema and dynamic)                                      |
+| **Controlled**  | You wrote the component. The agent picks which one to use and what data to pass.           | Tool call rendering, state rendering, reasoning, components as tools |
+| **Declarative** | The agent emits a structured spec. The frontend composes it from a catalog you registered. | A2UI (fixed-schema and flexible variants)                            |
 | **Open-ended**  | The UI is invented elsewhere (an MCP server) and you sandbox it.                           | MCP Apps                                                             |
 
 Each tier is a Mastra agent exposed through `registerCopilotKit()` (see [CopilotKit overview](https://mastra.ai/guides/build-your-ui/copilotkit/overview)) plus the matching CopilotKit hook on the frontend. For the full concept, see CopilotKit's [generative UI spectrum](https://www.copilotkit.ai/generative-ui-spectrum) and [generative UI overview](https://docs.copilotkit.ai/concepts/generative-ui-overview).
 
-> **Tip:** Mastra's [UI Dojo](https://ui-dojo.mastra.ai/) has working CopilotKit examples; browse the source under `src/pages/copilot-kit`.
+> **Tip:** Mastra's [UI Dojo](https://ui-dojo.mastra.ai/) has working CopilotKit examples. Browse the source under `src/pages/copilot-kit`.
 
 ## Controlled
 
-You ship a fixed set of components and the agent chooses which to render, with what data. This is the workhorse of the spectrum: predictable and brand-safe, the right tool for high-traffic surfaces. The Controlled primitives use CopilotKit's v2 API, imported from `@copilotkit/react-core/v2`.
+You provide a fixed set of components. The agent chooses which component to render and supplies its data. This predictable, brand-safe approach works well for high-traffic surfaces. The Controlled primitives use CopilotKit's v2 API, imported from `@copilotkit/react-core/v2`.
 
 ### Tool call rendering
 
@@ -125,7 +125,7 @@ Reasoning is zero-config: when your Mastra agent runs a reasoning-capable model,
 
 ## Declarative
 
-Instead of a fixed component per tool, you register a catalog of typed building blocks and the agent assembles them into a UI tree per request. CopilotKit calls this **A2UI** (Agent-to-UI), available in a fixed-schema and a dynamic variant. It suits the long tail of secondary interactions where breadth matters more than pixel-perfection.
+Instead of a fixed component per tool, you register a catalog of typed building blocks and the agent assembles them into a UI tree per request. CopilotKit calls this **A2UI** (Agent-to-UI), which has fixed-schema and flexible variants. It suits the long tail of secondary interactions where breadth matters more than pixel-perfection.
 
 The path of least resistance is to pass your catalog to the `<CopilotKit>` provider. That single prop enables A2UI rendering and injects the A2UI tool into your agent, so no backend change is needed:
 
@@ -146,11 +146,11 @@ export default function Page() {
 }
 ```
 
-The catalog defines the primitives (their schemas) and the renderers (how each primitive displays). In the fixed-schema variant the components are pre-authored and the agent's tool only supplies data; the dynamic variant lets the agent compose the tree more freely. See CopilotKit's [A2UI documentation](https://docs.copilotkit.ai/a2a/generative-ui/a2ui).
+The catalog defines the primitives (their schemas) and the renderers (how each primitive displays). In the fixed-schema variant, the components are pre-authored and the agent's tool only supplies data. The flexible variant lets the agent compose the tree more freely. See CopilotKit's [A2UI documentation](https://docs.copilotkit.ai/a2a/generative-ui/a2ui).
 
 ## Open-ended
 
-At the far end of the spectrum, the agent owns the entire surface: the UI is invented elsewhere and sandboxed in your app. CopilotKit supports this through **MCP Apps**, where an MCP server ships UI that renders inside your application. This tier trades determinism for novelty and is the most experimental point on the spectrum.
+At the far end of the spectrum, the agent owns the entire surface: the UI is invented elsewhere and sandboxed in your app. CopilotKit supports this through **MCP Apps**, where an MCP server provides UI that renders inside your application. This tier trades determinism for novelty and is the most experimental point on the spectrum.
 
 The path of least resistance keeps the frontend untouched: your existing `<CopilotKit>` provider is enough. On the backend, point `registerCopilotKit()` at one or more MCP servers with the `mcpApps` option (it's forwarded to the CopilotKit runtime):
 

package/.docs/guides/build-your-ui/copilotkit/overview.md

@@ -2,7 +2,7 @@
 
 # Using CopilotKit
 
-[CopilotKit](https://www.copilotkit.ai/) provides React components to quickly integrate customizable AI copilots into your application. Combined with Mastra, you can build sophisticated AI apps featuring bidirectional state synchronization and interactive UIs.
+[CopilotKit](https://www.copilotkit.ai/) provides React components to quickly integrate customizable AI copilots into your application. Combined with Mastra, you can build AI apps with bidirectional state synchronization and interactive UIs.
 
 CopilotKit talks to Mastra through the [AG-UI protocol](https://docs.ag-ui.com/). The `@ag-ui/mastra` package exposes your Mastra agents as an AG-UI endpoint, and CopilotKit's React hooks and components consume it. This unlocks a spectrum of experiences on top of ordinary chat: [generative UI, human-in-the-loop, and frontend tools](https://mastra.ai/guides/build-your-ui/copilotkit/generative-ui), plus deploying the same agent to [messaging channels like Slack](https://mastra.ai/guides/build-your-ui/copilotkit/channels).
 
@@ -266,7 +266,7 @@ Your CopilotKit frontend now communicates with a standalone Mastra agent server.
 
 ## Chat UI options
 
-`CopilotChat` renders an inline, full-height chat. CopilotKit ships two other drop-in surfaces that share the same props:
+`CopilotChat` renders an inline, full-height chat. CopilotKit provides two other drop-in surfaces that share the same props:
 
 - `CopilotSidebar`: a collapsible panel docked to the side of your app.
 - `CopilotPopup`: a floating button that opens a chat window.

package/.docs/guides/build-your-ui/openui.md

@@ -253,7 +253,7 @@ OpenUI generates UI from a component library. The library defines which componen
 
 ### Built-in libraries
 
-`@openuidev/react-ui` ships two libraries you can use as-is:
+`@openuidev/react-ui` provides two libraries you can use as-is:
 
 - `openuiChatLibrary`: components for chat interfaces (cards, forms, tables, charts).
 - `openuiDashboardLibrary`: components for dashboards and data-heavy surfaces.

package/.docs/guides/concepts/multi-agent-systems.md

@@ -4,7 +4,7 @@
 
 A multi-agent system distributes a task across multiple agents instead of asking one agent to do everything. In Mastra, this usually means combining agents, workflows, or both so each part of the system has a clear role.
 
-The goal is to assign the right context, tools, and responsibilities to the right component. When that split is clear, a multi-agent system can be easier to reason about than one agent with a long prompt, many tools, and too many responsibilities.
+The goal is to assign the right context, tools, and responsibilities to the right component. When that split is clear, a multi-agent system can be easier to reason about than one agent burdened with a long prompt and too many tools or responsibilities.
 
 ## When to use multi-agent systems
 
@@ -34,9 +34,9 @@ In Mastra, implement this pattern by combining [agents](https://mastra.ai/docs/a
 
 A workflow pattern defines the execution path in code. Instead of asking an agent to decide what happens next, you define the sequence through steps, branches, loops, and parallel blocks.
 
-Use workflows when the task is well understood and the execution path is known in advance. The main advantage is predictability: The system is easier to debug, reason about, and audit because the structure is explicit. The tradeoff is flexibility, since workflows are less adaptive when the task changes as it unfolds.
+Use workflows when the task is well understood and the execution path is known in advance. The main advantage is predictability: The explicit structure makes the system easier to debug and audit. The tradeoff is flexibility, since workflows are less adaptive when the task changes as it unfolds.
 
-In Mastra, [workflows](https://mastra.ai/docs/workflows/overview) can implement several coordination patterns, including handoffs and councils. What makes a workflow distinct isn't which agents it calls, but that the control logic lives in the workflow itself.
+In Mastra, [workflows](https://mastra.ai/docs/workflows/overview) can implement coordination patterns such as handoffs and councils. A workflow is distinct because its control logic lives in the workflow itself, regardless of which agents it calls.
 
 ## Supervisors
 
@@ -54,7 +54,7 @@ A council pattern asks multiple agents to work on the same problem independently
 
 Use this pattern when the question is ambiguous, evaluative, or high-stakes and answer quality matters more than speed. The tradeoff is cost, since councils intentionally duplicate effort and usually take longer and use more tokens than other patterns.
 
-Mastra doesn't provide a dedicated council primitive. In Mastra, implement this pattern with [agents](https://mastra.ai/docs/agents/overview) and [workflows](https://mastra.ai/docs/workflows/overview): Run multiple agents in parallel, collect their outputs, and add a final synthesis or review step. Workflow control flow methods such as `.parallel()` provide the structure for this pattern.
+Mastra doesn't provide a dedicated council primitive. In Mastra, implement this pattern with [agents](https://mastra.ai/docs/agents/overview) and [workflows](https://mastra.ai/docs/workflows/overview): Run multiple agents in parallel and collect their outputs. Then add a final synthesis or review step. Workflow control flow methods such as `.parallel()` provide the structure for this pattern.
 
 ## Choosing a pattern
 
@@ -64,7 +64,7 @@ These patterns differ mainly in how they distribute control:
 | ----------------- | -------------------- | ------------------------------------------------ | -------------------------------------------------------- | -------------------------------------------------------------------- |
 | Handoffs          | Current specialist   | Ownership should move between specialists        | Context transfer becomes more important                  | Agents with workflows and memory                                     |
 | Workflows         | Execution graph      | The path is known in advance                     | Less adaptive when the task changes                      | [Workflows](https://mastra.ai/docs/workflows/overview)               |
-| Supervisor agents | One lead agent       | The task needs dynamic delegation                | Results depend on good coordination and clear boundaries | [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) |
+| Supervisor agents | One lead agent       | Delegation must adapt during execution           | Results depend on good coordination and clear boundaries | [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) |
 | Council           | Final synthesis step | The task needs multiple independent perspectives | Higher cost and latency                                  | Agents with workflow parallelism                                     |
 
 In practice, these patterns are often combined:

package/.docs/guides/concepts/streaming.md

@@ -46,7 +46,7 @@ Here are some questions to consider:
 
 ### Agent stream properties
 
-An agent stream provides access to various response properties:
+An agent stream provides access to these response properties:
 
 - **`stream.textStream`**: A readable stream that emits text chunks.
 - **`stream.text`**: Promise that resolves to the full text response.
@@ -124,13 +124,13 @@ The event structure includes `runId` and `from` at the top level, making it easi
 
 ### Workflow stream properties
 
-A workflow stream provides access to various response properties:
+A workflow stream provides access to these response properties:
 
 - **`stream.status`**: The status of the workflow run.
 - **`stream.result`**: The result of the workflow run.
 - **`stream.usage`**: The total token usage of the workflow run.
 
-Streaming from agents or workflows provides real-time visibility into either the LLM’s output or the status of a workflow run. This feedback can be passed directly to the user, or used within applications to handle workflow status more effectively, creating a smoother and more responsive experience.
+Streaming from agents or workflows provides real-time visibility into either the LLM’s output or the status of a workflow run. Pass this feedback directly to the user, or use it in an application to display workflow status as it changes.
 
 Events emitted from agents or workflows represent different stages of generation and execution, such as when a run starts, when text is produced, or when a tool is invoked.
 
@@ -193,11 +193,11 @@ Below is an example of events that may be emitted. Each event always includes a
 
 ## Writer API
 
-The `writer` API is shared by tools and workflow steps — see the Tools and Workflows docs for feature-specific examples.
+The `writer` API is shared by tools and workflow steps. See the Tools and Workflows docs for feature-specific examples.
 
 ## Agent using tool
 
-Agent streaming can be combined with tool calls, allowing tool outputs to be written directly into the agent’s streaming response. This makes it possible to surface tool activity as part of the overall interaction.
+Agent streaming can be combined with tool calls, allowing tool outputs to be written directly into the agent’s streaming response. This surfaces tool activity as part of the interaction.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -214,7 +214,7 @@ export const testAgent = new Agent({
 
 ### Using `context.writer`
 
-The `context.writer` object is available in a tool's `execute()` function and can be used to emit custom events, data, or values into the active stream. This enables tools to provide intermediate results or status updates while execution is still in progress.
+The `context.writer` object is available in a tool's `execute()` function and can emit custom events, data, or values into the active stream. Tools use these events to provide intermediate results or status updates during execution.
 
 > **Warning:** You must `await` the call to `writer.write()` or else you will lock the stream and get a `WritableStream is locked` error.
 
@@ -274,7 +274,7 @@ export const testTool = createTool({
 
 ### Transient data chunks
 
-By default, `data-*` chunks emitted with `writer.custom()` are persisted to storage as part of the message history. For chunks that are only needed during live streaming — such as progress updates or verbose log output — set `transient: true` to skip storage persistence. Transient chunks are still streamed to the client in real time but aren't saved to the database.
+By default, `data-*` chunks emitted with `writer.custom()` are persisted to storage as part of the message history. For chunks that are only needed during live streaming, such as progress updates or verbose log output, set `transient: true` to skip storage persistence. Transient chunks are still streamed to the client in real time but aren't saved to the database.
 
 ```typescript
 await context?.writer?.custom({
@@ -284,11 +284,11 @@ await context?.writer?.custom({
 })
 ```
 
-Use transient chunks when the data is large or high-frequency and only relevant during the live session. After a page refresh, transient chunks are no longer available — only the tool's return value and any non-transient chunks are loaded from storage.
+Use transient chunks when the data is large or high-frequency and only relevant during the live session. After a page refresh, transient chunks are no longer available. Only the tool's return value and any non-transient chunks are loaded from storage.
 
 ## Using the `writer` argument
 
-The `writer` argument is passed to a workflow step's `execute` function and can be used to emit custom events, data, or values into the active stream. This enables workflow steps to provide intermediate results or status updates while execution is still in progress.
+The `writer` argument is passed to a workflow step's `execute` function and can emit custom events, data, or values into the active stream. Workflow steps use these events to provide intermediate results or status updates during execution.
 
 > **Warning:** You must `await` the call to `writer.write(...)` or else you will lock the stream and get a `WritableStream is locked` error.
 

package/.docs/guides/deployment/amazon-ec2.md

@@ -2,7 +2,7 @@
 
 # Deploy Mastra to Amazon EC2
 
-Deploy your Mastra server to Amazon EC2. This gives you full control over your server environment and supports long-running agents and workflows.
+Deploy your Mastra server to Amazon EC2. The server runs on infrastructure you manage and can support long-running agents and workflows.
 
 > **Info:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/mastra-server). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
 

package/.docs/guides/deployment/aws-lambda.md

@@ -12,7 +12,7 @@ You'll need:
 
 - A [Mastra application](https://mastra.ai/guides/getting-started/quickstart)
 - An [AWS account](https://aws.amazon.com/) with permissions for Lambda, ECR, and IAM
-- **[AWS CLI](https://aws.amazon.com/cli/)** installed — run `aws configure` to authenticate
+- **[AWS CLI](https://aws.amazon.com/cli/)** installed: Run `aws configure` to authenticate
 - **[Docker](https://www.docker.com/)** installed and running
 
 > **Warning:** On AWS Lambda, the filesystem is ephemeral, so any local database file will be lost between invocations. If you're using [LibSQLStore](https://mastra.ai/reference/storage/libsql) with a local file, configure it to use a remote LibSQL-compatible database (for example, [Turso](https://turso.tech/)) instead.

package/.docs/guides/deployment/azure-app-services.md

@@ -71,7 +71,7 @@ In these steps, you'll connect your Azure App Service to your GitHub repository
    run: (cd .mastra/output && zip ../../release.zip -r .)
    ```
 
-   This ensures only the build outputs from `.mastra/output` are included in the deployment package.
+   The deployment package then contains only the build outputs from `.mastra/output`.
 
 5. Commit and push your workflow modifications. The build will be automatically triggered in the **Deployment Center** in your Azure dashboard. Monitor the deployment progress until it completes successfully.
 

package/.docs/guides/deployment/cloudflare.md

@@ -56,7 +56,7 @@ export const mastra = new Mastra({
 })
 ```
 
-In order to test your Cloudflare Worker locally, also install the [`wrangler` CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/):
+To test your Cloudflare Worker locally, also install the [`wrangler` CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/):
 
 **npm**:
 

package/.docs/guides/deployment/inngest.md

@@ -8,11 +8,11 @@ For a complete example with advanced flow control features, see the [Inngest wor
 
 ## How Inngest works with Mastra
 
-Inngest and Mastra integrate by aligning their workflow models: Inngest organizes logic into functions composed of steps, and Mastra workflows defined using `createWorkflow()` and `createStep()` map directly onto this paradigm. Each Mastra workflow becomes an Inngest function with a unique identifier, and each step within the workflow maps to an Inngest step.
+Inngest and Mastra integrate by aligning their workflow models: Inngest organizes logic into functions composed of steps, and Mastra workflows defined using `createWorkflow()` and `createStep()` map directly onto this structure. Each Mastra workflow becomes an Inngest function with a unique identifier, and each step within the workflow maps to an Inngest step.
 
 The `serve()` function bridges the two systems by registering Mastra workflows as Inngest functions and setting up the necessary event handlers for execution and monitoring.
 
-When an event triggers a workflow, Inngest executes it step by step, memoizing each step's result. This means if a workflow is retried or resumed, completed steps are skipped, ensuring efficient and reliable execution. Control flow primitives in Mastra, such as loops, conditionals, and nested workflows are seamlessly translated into the same Inngest's function/step model, preserving advanced workflow features like composition, branching, and suspension.
+When an event triggers a workflow, Inngest executes it step by step and memoizes each result. On retry or resume, Inngest skips completed steps based on those saved results. Mastra control flow primitives, such as loops, conditionals, and nested workflows, map to the same Inngest function and step model while preserving composition, branching, and suspension.
 
 Real-time monitoring, suspend/resume, and step-level observability are enabled via Inngest's publish-subscribe system and dashboard. As each step executes, its state and output are tracked using Mastra storage and can be resumed as needed.
 
@@ -194,7 +194,7 @@ export const mastra = new Mastra({
 
 3. Open the Inngest Dashboard at <http://localhost:8288> and go to the **Apps** section in the sidebar to verify your Mastra workflow is registered
 
-4. Invoke the workflow by going to **Functions**, selecting your workflow, and selecting **Invoke** with the following input:
+4. In **Functions**, open your workflow. Select **Invoke** and provide the following input:
 
    ```json
    {
@@ -256,7 +256,7 @@ Before you begin, make sure you have:
 
    > **Warning:** Inngest's auto-discover convention assumes `/api/inngest`. Because this guide uses `/inngest/api`, set the **URL** field on the Inngest app to your deployed origin plus `/inngest/api` (for example `https://your-app.vercel.app/inngest/api`). If you leave it on the default, the Inngest dashboard won't find your app's functions.
 
-6. Invoke the workflow by going to **Functions**, selecting `workflow.increment-workflow`, selecting **All actions** > **Invoke**, and providing the following input:
+6. In **Functions**, open `workflow.increment-workflow`. Select **All actions** > **Invoke** and provide the following input:
 
    ```json
    {
@@ -496,7 +496,7 @@ When migrating an existing production app from `serve()` to `connect()`, test th
 - `functions`: Optional array of additional Inngest functions to register alongside Mastra workflows.
 - `instanceId`: Stable identifier for the worker, shown in the Inngest dashboard. Defaults to the machine hostname.
 - `maxWorkerConcurrency`: Maximum number of steps the worker runs at a time. Defaults to unlimited.
-- `registerOptions`: Forwarded to Inngest during app registration (for example `signingKey`). When a field is set both here and at the top level, `registerOptions` wins — this matches the behavior of `serve()`.
+- `registerOptions`: Forwarded to Inngest during app registration (for example `signingKey`). When a field is set both here and at the top level, `registerOptions` wins. This matches the behavior of `serve()`.
 
 `connect()` returns Inngest's `WorkerConnection`. The Inngest SDK handles `SIGINT` and `SIGTERM` by default. Store the returned connection and call `.close()` only when your worker needs custom shutdown control.
 
@@ -663,7 +663,7 @@ All flow control options are optional. If not specified, workflows run with Inng
 
 ## Cron scheduling
 
-Inngest workflows can be automatically triggered on a schedule using cron expressions. This allows you to run workflows at regular intervals, such as daily reports, hourly data syncs, or maintenance tasks.
+Use cron expressions to trigger Inngest workflows on a schedule. Common uses include daily reports and hourly data syncs, as well as maintenance tasks.
 
 ### Basic cron scheduling
 

package/.docs/guides/deployment/temporal.md

@@ -171,7 +171,7 @@ await worker.run()
 
 2. Open the Temporal UI at <http://localhost:8080> to inspect namespaces, workflows, and activities.
 
-3. Start the worker. In a new terminal, run:
+3. In a new terminal, start the worker by running:
 
    ```bash
    npx tsx src/mastra/worker.ts

package/.docs/guides/deployment/vercel.md

@@ -84,7 +84,7 @@ export const mastra = new Mastra({
 })
 ```
 
-After deploying, Studio is available at the root URL (`https://<your-project>.vercel.app/`) and the API remains at `/api/*`. Studio automatically connects to the API on the same origin — no additional environment variables are needed.
+After deploying, Studio is available at the root URL (`https://<your-project>.vercel.app/`) and the API remains at `/api/*`. Studio automatically connects to the API on the same origin, so you don't need additional environment variables.
 
 > **Warning:** Once Studio is connected to your Mastra server, it has full access to your agents, workflows, and tools. Be sure to secure it properly in production (e.g. behind authentication, VPN, etc.) to prevent unauthorized access.
 

package/.docs/guides/getting-started/astro.md

@@ -74,7 +74,7 @@ export default defineConfig({
 })
 ```
 
-Lastly, edit the `tsconfig.json` to resolve paths:
+Edit the `tsconfig.json` to resolve paths:
 
 ```jsonc
 {

package/.docs/guides/getting-started/electron.md

@@ -432,7 +432,7 @@ This connects [`useChat()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat
 
 ## Test your agent
 
-In order to test your agent with the chat interface, you need to run both the Mastra server and the Electron app.
+To test your agent with the chat interface, run both the Mastra server and the Electron app.
 
 1. Start the mastra development server:
 

package/.docs/guides/getting-started/nestjs.md

@@ -199,11 +199,11 @@ export class AgentService {
 
 `MastraService` exposes:
 
-- `getMastra()` — returns the underlying `Mastra` instance
-- `getAgent(id)` — shorthand for `mastra.getAgent(id)`
-- `getWorkflow(id)` — shorthand for `mastra.getWorkflow(id)`
-- `getOptions()` — returns the module configuration
-- `isShuttingDown` — `true` after graceful shutdown begins
+- `getMastra()`: Returns the underlying `Mastra` instance
+- `getAgent(id)`: Shorthand for `mastra.getAgent(id)`
+- `getWorkflow(id)`: Shorthand for `mastra.getWorkflow(id)`
+- `getOptions()`: Returns the module configuration
+- `isShuttingDown`: `true` after graceful shutdown begins
 
 ### MASTRA token
 

package/.docs/guides/getting-started/vite-react.md

@@ -353,7 +353,7 @@ It renders the response text using the [`<MessageResponse>`](https://ai-sdk.dev/
 
 ## Test your agent
 
-In order to test your agent with the chat interface, you need to run both the Mastra server and the Vite development server.
+To test your agent with the chat interface, run both the Mastra server and the Vite development server.
 
 1. Start the Mastra development server:
 

package/.docs/guides/guide/chef-michel.md

@@ -4,7 +4,7 @@
 
 In this guide, you'll create a "Chef Assistant" agent that helps users cook meals with available ingredients.
 
-You'll learn how to create the agent and register it with Mastra. Next, you'll interact with the agent through your terminal and get to know different response formats. Lastly, you'll access the agent through Mastra's local API endpoints.
+You'll learn how to create the agent and register it with Mastra. Next, you'll interact with the agent through your terminal and get to know different response formats. You'll then access the agent through Mastra's local API endpoints.
 
 ## Prerequisites
 

package/.docs/guides/guide/code-review-bot.md

@@ -2,7 +2,7 @@
 
 # Building a code review bot
 
-In this guide, you'll build a code review bot that automatically reviews pull requests using workspace skills. The bot loads coding standards from skill files and provides structured feedback. You'll learn how to create a workspace with a skills directory, define an [Agent Skill](https://agentskills.io) with review instructions and reference files, and connect it to an agent that performs automated reviews.
+In this guide, you'll build a code review bot that automatically reviews pull requests using workspace skills. The bot loads coding standards from skill files and provides structured feedback. You'll create a workspace with a skills directory and define an [Agent Skill](https://agentskills.io) with review instructions and reference files. Then you'll connect the skill to an agent that performs automated reviews.
 
 ## Prerequisites
 

package/.docs/guides/guide/coding-agent.md

@@ -146,7 +146,7 @@ Open [Studio](https://mastra.ai/docs/studio/overview), select **Coding Agent**,
 Inspect project-notes.md and report the project name, status, and owner. Do not modify files.
 ```
 
-The response should identify the Acme support portal, its development status, and the Platform team without changing the file. Model wording may vary.
+The response should identify the Acme support portal and describe its development status. It should report that the Platform team owns the project and leave the file unchanged. Model wording may vary.
 
 ## Create the agent controller
 
@@ -191,13 +191,13 @@ export async function createCodingAgentSession() {
 }
 ```
 
-This example uses one mode and disables the controller's additional built-in tools so the introductory UI can focus on workspace execution. This is a tutorial simplification, not a production recommendation. In a production application, enable the built-in tools your product needs and implement their UI flows: interactive tools such as `ask_user` and `submit_plan` suspend until your interface resumes them, while task and subagent tools have their own lifecycle events. See [tool approvals and suspensions](https://mastra.ai/docs/agent-controller/tool-approvals).
+This example uses one mode and disables the controller's additional built-in tools so the introductory UI can focus on workspace execution. The simplified setup is intended for this tutorial. In a production application, enable the built-in tools your product needs and implement their UI flows: interactive tools such as `ask_user` and `submit_plan` suspend until your interface resumes them, while task and subagent tools have their own lifecycle events. See [tool approvals and suspensions](https://mastra.ai/docs/agent-controller/tool-approvals).
 
 The example also omits storage, so the conversation lasts only for the current process. You can add storage later when you want to resume sessions.
 
 ## Build the terminal UI
 
-Create `src/coding-agent-tui.ts`. The UI renders assistant message updates, shows tool activity, and asks the user to approve or decline each workspace tool call.
+Create `src/coding-agent-tui.ts`. The UI renders assistant message updates and shows tool activity. It also asks the user to approve or decline each workspace tool call.
 
 ```typescript
 import { pathToFileURL } from 'node:url'
@@ -334,7 +334,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
 }
 ```
 
-The optional `Terminal` parameter supports automated tests while using `ProcessTerminal` during normal execution. The UI intentionally renders only the latest response; the `Session` still maintains the conversation context for follow-up prompts.
+The optional `Terminal` parameter supports automated tests while using `ProcessTerminal` during normal execution. The UI intentionally renders only the latest response. The `Session` still maintains the conversation context for follow-up prompts.
 
 ## Run the coding agent
 

package/.docs/guides/guide/dev-assistant.md

@@ -9,7 +9,7 @@ In this guide, you'll build a complete development assistant that combines all w
 - [Skills](https://mastra.ai/docs/workspace/skills) for coding standards
 - [Search](https://mastra.ai/docs/workspace/search) for finding examples
 
-You'll set up a workspace with a sample project, add coding standards as a skill, and create an agent that writes code following TDD practices. By the end, you'll have an agent that can read existing code, write new implementations, run tests in a sandbox, and iterate based on results.
+You'll set up a workspace with a sample project and add coding standards as a skill. Then you'll create an agent that writes code following TDD practices. By the end, the agent can read existing code and write new implementations, then run tests in a sandbox and iterate based on the results.
 
 ## Prerequisites
 

package/.docs/guides/guide/docs-manager.md

@@ -2,7 +2,7 @@
 
 # Building a docs manager
 
-In this guide, you'll build a documentation manager that maintains your project's docs. It creates well-structured markdown files, keeps documentation organized, and prevents accidental overwrites. You'll learn how to set up a workspace filesystem, create an agent with document management instructions, and use it to generate and update documentation through conversational prompts.
+In this guide, you'll build a documentation manager that maintains your project's docs. It creates well-structured markdown files and keeps documentation organized while preventing accidental overwrites. You'll set up a workspace filesystem and create an agent with document management instructions. Then you'll use conversational prompts to generate and update documentation.
 
 ## Prerequisites
 
@@ -40,7 +40,7 @@ Inside the `workspace` directory, create the following folders:
 - `docs/api/`: For API reference documentation
 - `docs/tutorials/`: For step-by-step tutorials
 
-Create a `workspace/docs/README.md` file that serves as the documentation index:
+Create `workspace/docs/README.md` as the documentation index:
 
 ```markdown
 # Project Documentation
@@ -217,7 +217,7 @@ Try updating an existing document:
 Update the getting started guide to include a section on configuration after the Quick Example
 ```
 
-The agent should read the existing `getting-started.md` file, find the right insertion point, and add the new section without disrupting existing content.
+The agent should read the existing `getting-started.md` file and find the right insertion point. It should add the new section without disrupting existing content.
 
 ### Organize documentation
 

package/.docs/guides/guide/github-actions-pr-description.md

@@ -121,11 +121,11 @@ The agent will return a formatted description with sections in English, Spanish,
 
 ## GitHub actions
 
-GitHub Actions run your workflows in short-lived environments on GitHub's infrastructure. Each run starts with a clean virtual machine, checks out your code, installs dependencies, runs your workflow steps, and then shuts down. Nothing persists between runs unless you explicitly save it as an artifact or cache.
+GitHub Actions run your workflows in short-lived environments on GitHub's infrastructure. Each run starts with a clean virtual machine and checks out your code. It installs dependencies before running your workflow steps. The environment shuts down when the run completes. Nothing persists between runs unless you explicitly save it as an artifact or cache.
 
 ### Create the workflow
 
-GitHub Actions workflows live in the `.github/workflows` directory. Create a `.github` directory at the root of your project, then create a `workflows` directory inside it. Add a file named `pr-description.yml`.
+GitHub Actions workflows live in the `.github/workflows` directory. Create a `.github` directory at the root of your project, then create a `workflows` directory inside it. Add `pr-description.yml`.
 
 This workflow runs whenever a pull request is opened or updated. It generates a diff for the PR, calls the Mastra agent to describe the changes, and writes the description directly into the PR in the GitHub UI.
 
@@ -187,7 +187,7 @@ jobs:
 
 ### Create the workflow script
 
-Create a `scripts` directory inside `.github` and add a file named `generate-description.ts`.
+Create a `scripts` directory inside `.github` and add `generate-description.ts`.
 
 This script reads the PR diff from `PR_DIFF_FILE`, generates a description using the Mastra agent, and writes the result to `PR_DESCRIPTION_FILE` for the workflow to publish to the pull request.
 
@@ -229,7 +229,7 @@ ${readFileSync(process.env.PR_DIFF_FILE!, 'utf-8')}
 
 You now have a GitHub Action that generates multi-language PR descriptions using a Mastra agent. Once the workflow and supporting files are merged into your main branch, the agent will run automatically the next time a pull request is created or updated. You can monitor the run in the **Actions** tab of your repository.
 
-From here, you can customize the agent instructions, change the output languages, or extend the workflow to handle other events.
+From here, customize the agent instructions or change the output languages. You can also extend the workflow to handle other events.
 
 To learn more:
 

package/.docs/guides/guide/research-assistant.md

@@ -4,7 +4,7 @@
 
 In this guide, you'll create an AI research assistant that can analyze academic papers and answer specific questions about their content using Retrieval Augmented Generation (RAG).
 
-You'll use the foundational Transformer paper ["Attention Is All You Need"](https://arxiv.org/html/1706.03762) as your example. As a database you'll use a local libSQL database.
+You'll use the original Transformer paper ["Attention Is All You Need"](https://arxiv.org/html/1706.03762) as your example. As a database you'll use a local libSQL database.
 
 ## Prerequisites
 
@@ -155,7 +155,7 @@ Let's define the agent's behavior, connect it to your Mastra project, and create
 
 ## Processing documents
 
-In the following steps you'll fetch the research paper, split it into smaller chunks, generate embeddings for them, and store these chunks of information into the vector database.
+In the following steps, you'll fetch the research paper and split it into smaller chunks. You'll then generate embeddings and store the chunks in the vector database.
 
 1. In this step the research paper is retrieved by providing an URL, then converted to a document object, and split into smaller, manageable chunks. By splitting into chunks the processing is faster and more efficient.
 
@@ -201,7 +201,7 @@ In the following steps you'll fetch the research paper, split it into smaller ch
 
    > **Note:** This metadata is crucial as it allows for returning the actual content when the vector store finds relevant matches.
 
-   This allows the agent to efficiently search and retrieve relevant information.
+   The agent uses the vector index to search for and retrieve relevant information.
 
    Open the `src/store.ts` file and add the following: