@mastra/mcp-docs-server 1.1.8-alpha.0 → 1.1.9-alpha.0

package/.docs/docs/observability/tracing/bridges/otel.md

@@ -23,7 +23,7 @@ The OtelBridge provides two-way integration:
 
 - Reads from OTEL ambient context (AsyncLocalStorage) automatically
 - Inherits trace ID and parent span ID from active OTEL spans
-- Respects OTEL sampling decisions — if a trace is not sampled, Mastra won't create spans for it
+- Respects OTEL sampling decisions — if a trace isn't sampled, Mastra won't create spans for it
 - No manual trace ID passing required when OTEL auto-instrumentation is active
 
 **From Mastra to OTEL:**
@@ -196,7 +196,7 @@ Tags are exported as a JSON string in the `mastra.tags` span attribute for broad
 
 ## Troubleshooting
 
-If traces aren't appearing or connecting as expected:
+If traces aren't displaying or connecting as expected:
 
 - Verify OTEL SDK is initialized before Mastra (use `--import` flag or import at top of entry point)
 - Ensure the OtelBridge is added to your observability config

package/.docs/docs/observability/tracing/exporters/default.md

@@ -124,7 +124,7 @@ If you set the strategy to `'auto'`, the `DefaultExporter` automatically selects
 
 ### Providers without Observability Support
 
-The following storage providers **do not support** the observability domain. If you're using one of these providers and need observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider:
+The following storage providers **don't support** the observability domain. If you're using one of these providers and need observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider:
 
 - [Convex](https://mastra.ai/reference/storage/convex)
 - [DynamoDB](https://mastra.ai/reference/storage/dynamodb)

package/.docs/docs/observability/tracing/overview.md

@@ -429,7 +429,7 @@ requestContext.set('session', { data: { experimentId: 'exp-999' } })
 
 ### Adding Tags to Traces
 
-Tags are string labels that help you categorize and filter traces. Unlike metadata (which contains structured key-value data), tags are simple strings designed for quick filtering and organization.
+Tags are string labels that help you categorize and filter traces. Unlike metadata (which contains structured key-value data), tags are plain strings designed for quick filtering and organization.
 
 Use `tracingOptions.tags` to add tags when executing agents or workflows:
 
@@ -617,11 +617,11 @@ Span processors transform, filter, or enrich trace data before it's exported. Th
 
 #### Built-in Processors
 
-- [Sensitive Data Filter](https://mastra.ai/docs/observability/tracing/processors/sensitive-data-filter) redacts sensitive information. It is enabled in the default observability config.
+- [Sensitive Data Filter](https://mastra.ai/docs/observability/tracing/processors/sensitive-data-filter) redacts sensitive information. It's enabled in the default observability config.
 
 #### Creating Custom Processors
 
-You can create custom span processors by implementing the `SpanOutputProcessor` interface. Here's a simple example that converts all input text in spans to lowercase:
+You can create custom span processors by implementing the `SpanOutputProcessor` interface. Here's a basic example that converts all input text in spans to lowercase:
 
 ```ts
 import type { SpanOutputProcessor, AnySpan } from '@mastra/observability'
@@ -667,7 +667,7 @@ Custom span formatters transform how spans appear in specific observability plat
 #### Use Cases
 
 - **Extract plain text from AI SDK messages** - Convert structured message arrays to readable text
-- **Transform input/output formats** - Customize how data appears in specific platforms
+- **Transform input/output formats** - Customize how data displays in specific platforms
 - **Platform-specific field mapping** - Add or remove fields based on platform requirements
 - **Async data enrichment** - Fetch additional context from external APIs or databases
 

package/.docs/docs/observability/tracing/processors/sensitive-data-filter.md

@@ -67,7 +67,7 @@ When a sensitive field is detected, its value is replaced with `[REDACTED]` by d
 
 ## Custom Configuration
 
-You can customize which fields are redacted and how redaction appears:
+You can customize which fields are redacted and how redaction displays:
 
 ```ts
 import { SensitiveDataFilter, DefaultExporter, Observability } from '@mastra/observability'
@@ -167,7 +167,7 @@ The filter uses intelligent field matching:
 3. **Exact Matching**: After normalization, fields must match exactly
 
    - `token` matches `token`, `Token`, `TOKEN`
-   - `token` does NOT match `promptTokens` or `tokenCount`
+   - `token` doesn't match `promptTokens` or `tokenCount`
 
 ## Nested Object Handling
 

package/.docs/docs/rag/chunking-and-embedding.md

@@ -123,7 +123,7 @@ const { embeddings } = await embedMany({
 })
 ```
 
-> **Vector Database Compatibility:** When storing embeddings, the vector database index must be configured to match the output size of your embedding model. If the dimensions do not match, you may get errors or data corruption.
+> **Vector Database Compatibility:** When storing embeddings, the vector database index must be configured to match the output size of your embedding model. If the dimensions don't match, you may get errors or data corruption.
 
 ## Example: Complete Pipeline
 

package/.docs/docs/rag/vector-databases.md

@@ -359,7 +359,7 @@ The dimension size must match the output dimension of your chosen embedding mode
 - Cohere embed-multilingual-v3: 1024 dimensions
 - Google gemini-embedding-001: 768 dimensions (or custom)
 
-> **Warning:** Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
+> **Warning:** Index dimensions can't be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
 
 ### Naming Rules for Databases
 
@@ -583,7 +583,7 @@ Key metadata considerations:
 
 ## Deleting Vectors
 
-When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it easy to remove all embeddings associated with a specific document.
+When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it straightforward to remove all embeddings associated with a specific document.
 
 ### Delete by Metadata Filter
 

package/.docs/docs/server/auth/auth0.md

@@ -66,7 +66,7 @@ export const mastra = new Mastra({
 By default, `MastraAuthAuth0` allows all authenticated users who have valid Auth0 tokens for the specified audience. The token verification ensures that:
 
 1. The token is properly signed by Auth0
-2. The token is not expired
+2. The token isn't expired
 3. The token audience matches your configured audience
 4. The token issuer matches your Auth0 domain
 

package/.docs/docs/server/auth/firebase.md

@@ -71,7 +71,7 @@ The `MastraAuthFirebase` class can be configured through constructor options or
 - `FIREBASE_SERVICE_ACCOUNT`: Path to Firebase service account JSON file
 - `FIRESTORE_DATABASE_ID` or `FIREBASE_DATABASE_ID`: Firestore database ID
 
-> **Note:** When constructor options are not provided, the class automatically reads these environment variables. This means you can simply call `new MastraAuthFirebase()` without any arguments if your environment variables are properly configured.
+> **Note:** When constructor options aren't provided, the class automatically reads these environment variables. This means you can call `new MastraAuthFirebase()` without any arguments if your environment variables are properly configured.
 
 ### User Authorization
 

package/.docs/docs/server/auth/simple-auth.md

@@ -1,6 +1,6 @@
 # SimpleAuth Class
 
-The `SimpleAuth` class provides token-based authentication using a simple token-to-user mapping. It's included in `@mastra/core/server` and is useful for development, testing, and simple API key authentication scenarios.
+The `SimpleAuth` class provides token-based authentication using a basic token-to-user mapping. It's included in `@mastra/core/server` and is useful for development, testing, and basic API key authentication scenarios.
 
 ## Use Cases
 

package/.docs/docs/server/auth.md

@@ -2,7 +2,7 @@
 
 Mastra lets you choose how you handle authentication, so you can secure access to your application's endpoints using the identity system that fits your stack.
 
-You can start with simple shared secret JWT authentication and switch to providers like Supabase, Firebase Auth, Auth0, Clerk, or WorkOS when you need more advanced identity features.
+You can start with basic shared secret JWT authentication and switch to providers like Supabase, Firebase Auth, Auth0, Clerk, or WorkOS when you need more advanced identity features.
 
 ## Default behavior
 

package/.docs/docs/server/mastra-client.md

@@ -1,6 +1,6 @@
 # Mastra Client SDK
 
-The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/server/mastra-server) from your client environment.
+The Mastra Client SDK provides a concise and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/server/mastra-server) from your client environment.
 
 ## Prerequisites
 

package/.docs/docs/server/mastra-server.md

@@ -51,7 +51,7 @@ This behavior is only configurable by using [server adapters](https://mastra.ai/
 
 ## TypeScript configuration
 
-Mastra requires `module` and `moduleResolution` settings compatible with modern Node.js. Legacy options like `CommonJS` or `node` are not supported.
+Mastra requires `module` and `moduleResolution` settings compatible with modern Node.js. Legacy options like `CommonJS` or `node` aren't supported.
 
 ```json
 {

package/.docs/docs/server/server-adapters.md

@@ -389,7 +389,7 @@ const server = new MastraServer({
 })
 ```
 
-With this prefix, Mastra routes become `/api/v2/agents`, `/api/v2/workflows`, etc. Custom routes you add directly to the app are not affected by this prefix.
+With this prefix, Mastra routes become `/api/v2/agents`, `/api/v2/workflows`, etc. Custom routes you add directly to the app aren't affected by this prefix.
 
 ## OpenAPI spec
 
@@ -487,7 +487,7 @@ The adapter reads these settings from `mastra.getServer()`:
 
 ### Adapter constructor only
 
-These options are passed directly to the adapter constructor and are not read from the Mastra config:
+These options are passed directly to the adapter constructor and aren't read from the Mastra config:
 
 | Option                  | Description                                                                 |
 | ----------------------- | --------------------------------------------------------------------------- |

package/.docs/docs/streaming/events.md

@@ -143,7 +143,7 @@ Each progress event includes:
 - **`id`**: The step ID of the foreach step
 - **`completedCount`**: Number of iterations completed so far
 - **`totalCount`**: Total number of iterations
-- **`currentIndex`**: Index of the iteration that just completed
+- **`currentIndex`**: Index of the iteration that completed
 - **`iterationStatus`**: Status of the iteration (`success`, `failed`, or `suspended`)
 - **`iterationOutput`**: Output of the iteration (when successful)
 

package/.docs/docs/streaming/overview.md

@@ -11,7 +11,7 @@ Mastra's streaming API adapts based on your model version:
 
 ## Streaming with agents
 
-You can pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content` for precise control over roles and conversational flows.
+You can pass a single string for basic prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content` for precise control over roles and conversational flows.
 
 ### Using `Agent.stream()`
 

package/.docs/docs/streaming/tool-streaming.md

@@ -5,7 +5,7 @@ Tool streaming in Mastra enables tools to send incremental results while they ru
 Streams can be written to in two main ways:
 
 - **From within a tool**: every tool receives a `context.writer` object, which is a writable stream you can use to push updates as execution progresses.
-- **From an agent stream**: you can also pipe an agent's `stream` output directly into a tool's writer, making it easy to chain agent responses into tool results without extra glue code.
+- **From an agent stream**: you can also pipe an agent's `stream` output directly into a tool's writer, making it convenient to chain agent responses into tool results without extra glue code.
 
 By combining writable tool streams with agent streaming, you gain fine grained control over how intermediate results flow through your system and into the user experience.
 
@@ -33,59 +33,73 @@ The `context.writer` object is available in a tool's `execute()` function and ca
 > **Warning:** You must `await` the call to `writer.write()` or else you will lock the stream and get a `WritableStream is locked` error.
 
 ```typescript
-import { createTool } from "@mastra/core/tools";
+import { createTool } from '@mastra/core/tools'
 
 export const testTool = createTool({
   execute: async (inputData, context) => {
-    const { value } = inputData;
+    const { value } = inputData
 
     await context?.writer?.write({
-      type: "custom-event",
-      status: "pending"
-    });
+      type: 'custom-event',
+      status: 'pending',
+    })
 
-    const response = await fetch(...);
+    const response = await fetch()
 
     await context?.writer?.write({
-      type: "custom-event",
-      status: "success"
-    });
+      type: 'custom-event',
+      status: 'success',
+    })
 
     return {
-      value: ""
-    };
-  }
-});
+      value: '',
+    }
+  },
+})
 ```
 
-You can also use `writer.custom()` if you want to emit top level stream chunks, This useful and relevant when integrating with UI Frameworks
+You can also use `writer.custom()` to emit top-level stream chunks. This is useful when integrating with UI frameworks.
 
 ```typescript
-import { createTool } from "@mastra/core/tools";
+import { createTool } from '@mastra/core/tools'
 
 export const testTool = createTool({
   execute: async (inputData, context) => {
-    const { value } = inputData;
+    const { value } = inputData
 
-   await context?.writer?.custom({
-      type: "data-tool-progress",
-      status: "pending"
-    });
+    await context?.writer?.custom({
+      type: 'data-tool-progress',
+      status: 'pending',
+    })
 
-    const response = await fetch(...);
+    const response = await fetch()
 
-   await context?.writer?.custom({
-      type: "data-tool-progress",
-      status: "success"
-    });
+    await context?.writer?.custom({
+      type: 'data-tool-progress',
+      status: 'success',
+    })
 
     return {
-      value: ""
-    };
-  }
-});
+      value: '',
+    }
+  },
+})
+```
+
+### 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.
+
+```typescript
+await context?.writer?.custom({
+  type: 'data-build-log',
+  data: { line: 'Compiling module 3 of 12...' },
+  transient: true,
+})
 ```
 
+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.
+
 ### Inspecting stream payloads
 
 Events written to the stream are included in the emitted chunks. These chunks can be inspected to access any custom fields, such as event types, intermediate values, or tool-specific data.

package/.docs/docs/streaming/workflow-streaming.md

@@ -5,7 +5,7 @@ Workflow streaming in Mastra enables workflows to send incremental results while
 Streams can be written to in two main ways:
 
 - **From within a workflow step**: every workflow step receives a `writer` argument, which is a writable stream you can use to push updates as execution progresses.
-- **From an agent stream**: you can also pipe an agent's `stream` output directly into a workflow step's writer, making it easy to chain agent responses into workflow results without extra glue code.
+- **From an agent stream**: you can also pipe an agent's `stream` output directly into a workflow step's writer, making it convenient to chain agent responses into workflow results without extra glue code.
 
 By combining writable workflow streams with agent streaming, you gain fine-grained control over how intermediate results flow through your system and into the user experience.
 

package/.docs/docs/workflows/control-flow.md

@@ -166,6 +166,48 @@ export const testWorkflow = createWorkflow({
 - The next step receives an object containing all parallel step outputs
 - You must define the `inputSchema` of the following step to match this structure
 
+### Handling step failures
+
+If any parallel step throws an error, the entire parallel block fails. To build resilient parallel workflows where some steps may fail — for example, multiple research agents where one might have an expired auth token — handle errors inside the step itself using try/catch:
+
+```typescript
+const resilientStep = createStep({
+  id: 'researcher',
+  inputSchema: z.object({ query: z.string() }),
+  outputSchema: z.object({
+    brief: z.string().nullable(),
+    failed: z.boolean(),
+  }),
+  execute: async ({ inputData }) => {
+    try {
+      const result = await fetchExternalData(inputData.query)
+      return { brief: result, failed: false }
+    } catch {
+      return { brief: null, failed: true }
+    }
+  },
+})
+```
+
+This way the step always succeeds with a typed result, and the downstream step can filter out failed results:
+
+```typescript
+const writerStep = createStep({
+  id: 'writer',
+  inputSchema: z.object({
+    'researcher-a': z.object({ brief: z.string().nullable(), failed: z.boolean() }),
+    'researcher-b': z.object({ brief: z.string().nullable(), failed: z.boolean() }),
+  }),
+  outputSchema: z.object({ synthesis: z.string() }),
+  execute: async ({ inputData }) => {
+    const briefs = Object.values(inputData)
+      .filter(v => !v.failed && v.brief)
+      .map(v => v.brief)
+    return { synthesis: briefs.join('; ') }
+  },
+})
+```
+
 > **Info:** Visit [Choosing the right pattern](#choosing-the-right-pattern) to understand when to use `.parallel()` vs `.foreach()`.
 
 ## Conditional logic with `.branch()`
@@ -292,7 +334,7 @@ export const testWorkflow = createWorkflow({
 
 ## Input data mapping
 
-When using `.then()`, `.parallel()`, or `.branch()`, it is sometimes necessary to transform the output of a previous step to match the input of the next. In these cases you can use `.map()` to access the `inputData` and transform it to create a suitable data shape for the next step.
+When using `.then()`, `.parallel()`, or `.branch()`, it's sometimes necessary to transform the output of a previous step to match the input of the next. In these cases you can use `.map()` to access the `inputData` and transform it to create a suitable data shape for the next step.
 
 ![Mapping with .map()](/assets/images/workflows-data-mapping-map-87fd84a06b4bbf4b93868a5db99ca179.jpg)
 
@@ -777,7 +819,7 @@ This means:
 
 - `.parallel()` collects all branch outputs into an object, then passes it to the next step
 - `.foreach()` collects all iteration outputs into an array, then passes it to the next step
-- There is no way to "stream" results to the next step as they complete
+- Results can't be "streamed" to the next step as they complete
 
 ### Concurrency behavior
 

package/.docs/docs/workflows/error-handling.md

@@ -166,7 +166,7 @@ const pipelineWorkflow = createWorkflow({
 
 ### Error handling in callbacks
 
-Errors thrown inside callbacks are caught and logged—they will not affect the workflow result or cause it to fail. This ensures that callback issues don't break your workflows in production.
+Errors thrown inside callbacks are caught and logged—they won't affect the workflow result or cause it to fail. This ensures that callback issues don't break your workflows in production.
 
 ```typescript
 options: {

package/.docs/docs/workflows/overview.md

@@ -140,7 +140,7 @@ export const testWorkflow = createWorkflow({
 
 ### Cloning a workflow
 
-Clone a workflow using `cloneWorkflow()` when you want to reuse its logic but track it separately under a new ID. Each clone runs independently and appears as a distinct workflow in logs and observability tools.
+Clone a workflow using `cloneWorkflow()` when you want to reuse its logic but track it separately under a new ID. Each clone runs independently and shows up as a distinct workflow in logs and observability tools.
 
 ```typescript
 import { cloneWorkflow } from "@mastra/core/workflows";
@@ -182,7 +182,7 @@ const testWorkflow = mastra.getWorkflow('testWorkflow')
 > 1. It provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores)
 > 2. It provides full TypeScript type inference for workflow input and output schemas
 >
-> **Note:** Use `getWorkflow()` with the workflow's **registration key** (the key used when adding it to Mastra). While `getWorkflowById()` is available for retrieving workflows by their `id` property, it does not provide the same level of type inference.
+> **Note:** Use `getWorkflow()` with the workflow's **registration key** (the key used when adding it to Mastra). While `getWorkflowById()` is available for retrieving workflows by their `id` property, it doesn't provide the same level of type inference.
 
 ## Running workflows
 
@@ -358,7 +358,7 @@ const step1 = createStep({
 
 ## Testing with Studio
 
-Use [Studio](https://mastra.ai/docs/getting-started/studio) to easily run workflows with different inputs, visualize the execution lifecycle, see the inputs and outputs for each step, and inspect each part of the workflow in more detail.
+Use [Studio](https://mastra.ai/docs/getting-started/studio) to run workflows with different inputs, visualize the execution lifecycle, see the inputs and outputs for each step, and inspect each part of the workflow in more detail.
 
 ## Related
 

package/.docs/docs/workflows/snapshots.md

@@ -150,7 +150,7 @@ export const mastra = new Mastra({
 1. **Ensure Serializability**: Any data that needs to be included in the snapshot must be serializable (convertible to JSON).
 2. **Minimize Snapshot Size**: Avoid storing large data objects directly in the workflow context. Instead, store references to them (like IDs) and retrieve the data when needed.
 3. **Handle Resume Context Carefully**: When resuming a workflow, carefully consider what context to provide. This will be merged with the existing snapshot data.
-4. **Set Up Proper Monitoring**: Implement monitoring for suspended workflows, especially long-running ones, to ensure they are properly resumed.
+4. **Set Up Proper Monitoring**: Implement monitoring for suspended workflows, especially long-running ones, to ensure they're properly resumed.
 5. **Consider Storage Scaling**: For applications with many suspended workflows, ensure your storage solution is appropriately scaled.
 
 ## Custom snapshot metadata

package/.docs/docs/workflows/time-travel.md

@@ -1,6 +1,6 @@
 # Time Travel
 
-Time travel allows you to re-execute a workflow starting from any specific step, using either stored snapshot data or custom context you provide. This is useful for debugging failed workflows, testing individual steps with different inputs, or recovering from errors without re-running the entire workflow. You can also use time travel to execute a workflow that has not been run yet, starting from any specific step.
+Time travel allows you to re-execute a workflow starting from any specific step, using either stored snapshot data or custom context you provide. This is useful for debugging failed workflows, testing individual steps with different inputs, or recovering from errors without re-running the entire workflow. You can also use time travel to execute a workflow that hasn't been run yet, starting from any specific step.
 
 ## How time travel works
 
@@ -193,7 +193,7 @@ Time travel throws errors in specific situations:
 
 ### Running workflow
 
-You cannot time travel to a workflow that is currently running:
+You can't time travel to a workflow that's currently running:
 
 ```typescript
 try {

package/.docs/docs/workspace/filesystem.md

@@ -101,7 +101,7 @@ const workspace = new Workspace({
 })
 ```
 
-When read-only, write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are not added to the agent's toolset. The agent can still read and list files.
+When read-only, write tools (`write_file`, `edit_file`, `delete`, `mkdir`) aren't added to the agent's toolset. The agent can still read and list files.
 
 ## Mounts and CompositeFilesystem
 
@@ -140,7 +140,7 @@ With this configuration:
 
 All file paths must start with a mount prefix. Operations on paths that don't match any mount will fail. Listing the root directory (`/`) returns virtual directory entries for each mount point.
 
-Mount paths cannot be nested — for example, you cannot mount at both `/data` and `/data/sub`.
+Mount paths can't be nested — for example, you can't mount at both `/data` and `/data/sub`.
 
 ### `filesystem` vs `mounts`
 

package/.docs/docs/workspace/overview.md

@@ -7,7 +7,7 @@ A Mastra workspace gives agents a persistent environment for storing files and e
 A workspace supports the following features:
 
 - **[Filesystem](https://mastra.ai/docs/workspace/filesystem)**: File storage (read, write, list, delete, copy, move, grep)
-- **[Sandbox](https://mastra.ai/docs/workspace/sandbox)**: Command execution (shell commands)
+- **[Sandbox](https://mastra.ai/docs/workspace/sandbox)**: Command execution (shell commands) and background processes
 - **[Search](https://mastra.ai/docs/workspace/search)**: BM25, vector, or hybrid search over indexed content
 - **[Skills](https://mastra.ai/docs/workspace/skills)**: Reusable instructions for agents
 
@@ -117,7 +117,7 @@ Under the hood, `mounts` creates a [CompositeFilesystem](https://mastra.ai/docs/
 
 You can mount multiple providers at different paths. Each mount path must be unique and non-overlapping.
 
-> **Note:** `filesystem` and `mounts` are mutually exclusive — you cannot use both in the same workspace. Use `filesystem` for a single provider without a sandbox, or `mounts` when you need to combine cloud storage with a sandbox.
+> **Note:** `filesystem` and `mounts` are mutually exclusive — you can't use both in the same workspace. Use `filesystem` for a single provider without a sandbox, or `mounts` when you need to combine cloud storage with a sandbox.
 
 ### Filesystem only
 
@@ -190,11 +190,56 @@ const workspace = new Workspace({
 
 ### Tool options
 
-| Option                   | Type      | Description                                                                 |
-| ------------------------ | --------- | --------------------------------------------------------------------------- |
-| `enabled`                | `boolean` | Whether the tool is available (default: `true`)                             |
-| `requireApproval`        | `boolean` | Whether the tool requires user approval before execution (default: `false`) |
-| `requireReadBeforeWrite` | `boolean` | For write tools: require reading the file first (default: `false`)          |
+| Option                   | Type      | Description                                                                                                |
+| ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------- |
+| `enabled`                | `boolean` | Whether the tool is available (default: `true`)                                                            |
+| `requireApproval`        | `boolean` | Whether the tool requires user approval before execution (default: `false`)                                |
+| `requireReadBeforeWrite` | `boolean` | For write tools: require reading the file first (default: `false`)                                         |
+| `name`                   | `string`  | Custom name for the tool. Replaces the default `mastra_workspace_*` name.                                  |
+| `maxOutputTokens`        | `number`  | Maximum tokens for tool output (default: `2000`). Output exceeding this limit is truncated using tiktoken. |
+
+### Tool name remapping
+
+Rename workspace tools to match the conventions your agent expects. The config key remains the original `WORKSPACE_TOOLS` constant — only the exposed name changes.
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+  tools: {
+    [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: { name: 'view' },
+    [WORKSPACE_TOOLS.FILESYSTEM.GREP]: { name: 'search_content' },
+    [WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES]: { name: 'find_files' },
+    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: { name: 'execute_command' },
+  },
+})
+```
+
+The agent sees `view`, `search_content`, `find_files`, and `execute_command` instead of the default `mastra_workspace_*` names. Tool names must be unique — duplicate names or conflicts with other default names throw an error.
+
+### Output truncation
+
+Workspace tools automatically truncate large outputs to avoid exceeding LLM context limits. Two layers of truncation apply:
+
+1. **Line-based tail**: Command output is limited to the last 200 lines by default (configurable per-command via the `tail` parameter)
+2. **Token-based limit**: Tool output is capped at 2000 tokens by default
+
+Set `maxOutputTokens` per tool to adjust the token limit:
+
+```typescript
+const workspace = new Workspace({
+  // ...
+  tools: {
+    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
+      maxOutputTokens: 5000,
+    },
+  },
+})
+```
+
+ANSI escape codes (colors, cursor sequences) are automatically stripped from command output before it reaches the model.
 
 ### Read-before-write