@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/voice/openai-realtime.md

@@ -0,0 +1,203 @@
+# OpenAI Realtime Voice
+
+The OpenAIRealtimeVoice class provides real-time voice interaction capabilities using OpenAI's WebSocket-based API. It supports real time speech to speech, voice activity detection, and event-based audio streaming.
+
+## Usage Example
+
+```typescript
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import { playAudio, getMicrophoneStream } from '@mastra/node-audio'
+
+// Initialize with default configuration using environment variables
+const voice = new OpenAIRealtimeVoice()
+
+// Or initialize with specific configuration
+const voiceWithConfig = new OpenAIRealtimeVoice({
+  apiKey: 'your-openai-api-key',
+  model: 'gpt-5.1-realtime-preview-2024-12-17',
+  speaker: 'alloy', // Default voice
+})
+
+voiceWithConfig.updateSession({
+  turn_detection: {
+    type: 'server_vad',
+    threshold: 0.6,
+    silence_duration_ms: 1200,
+  },
+})
+
+// Establish connection
+await voice.connect()
+
+// Set up event listeners
+voice.on('speaker', ({ audio }) => {
+  // Handle audio data (Int16Array) pcm format by default
+  playAudio(audio)
+})
+
+voice.on('writing', ({ text, role }) => {
+  // Handle transcribed text
+  console.log(`${role}: ${text}`)
+})
+
+// Convert text to speech
+await voice.speak('Hello, how can I help you today?', {
+  speaker: 'echo', // Override default voice
+})
+
+// Process audio input
+const microphoneStream = getMicrophoneStream()
+await voice.send(microphoneStream)
+
+// When done, disconnect
+voice.connect()
+```
+
+## Configuration
+
+### Constructor Options
+
+**model?:** (`string`): The model ID to use for real-time voice interactions. (Default: `'gpt-5.1-realtime-preview-2024-12-17'`)
+
+**apiKey?:** (`string`): OpenAI API key. Falls back to OPENAI\_API\_KEY environment variable.
+
+**speaker?:** (`string`): Default voice ID for speech synthesis. (Default: `'alloy'`)
+
+### Voice Activity Detection (VAD) Configuration
+
+**type?:** (`string`): Type of VAD to use. Server-side VAD provides better accuracy. (Default: `'server_vad'`)
+
+**threshold?:** (`number`): Speech detection sensitivity (0.0-1.0). (Default: `0.5`)
+
+**prefix\_padding\_ms?:** (`number`): Milliseconds of audio to include before speech is detected. (Default: `1000`)
+
+**silence\_duration\_ms?:** (`number`): Milliseconds of silence before ending a turn. (Default: `1000`)
+
+## Methods
+
+### connect()
+
+Establishes a connection to the OpenAI realtime service. Must be called before using speak, listen, or send functions.
+
+**returns:** (`Promise<void>`): Promise that resolves when the connection is established.
+
+### speak()
+
+Emits a speaking event using the configured voice model. Can accept either a string or a readable stream as input.
+
+**input:** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
+
+**options.speaker?:** (`string`): Voice ID to use for this specific speech request. (Default: `Constructor's speaker value`)
+
+Returns: `Promise<void>`
+
+### listen()
+
+Processes audio input for speech recognition. Takes a readable stream of audio data and emits a 'listening' event with the transcribed text.
+
+**audioData:** (`NodeJS.ReadableStream`): Audio stream to transcribe.
+
+Returns: `Promise<void>`
+
+### send()
+
+Streams audio data in real-time to the OpenAI service for continuous audio streaming scenarios like live microphone input.
+
+**audioData:** (`NodeJS.ReadableStream`): Audio stream to send to the service.
+
+Returns: `Promise<void>`
+
+### updateConfig()
+
+Updates the session configuration for the voice instance. This can be used to modify voice settings, turn detection, and other parameters.
+
+**sessionConfig:** (`Realtime.SessionConfig`): New session configuration to apply.
+
+Returns: `void`
+
+### addTools()
+
+Adds a set of tools to the voice instance. Tools allow the model to perform additional actions during conversations. When OpenAIRealtimeVoice is added to an Agent, any tools configured for the Agent will automatically be available to the voice interface.
+
+**tools?:** (`ToolsInput`): Tools configuration to equip.
+
+Returns: `void`
+
+### close()
+
+Disconnects from the OpenAI realtime session and cleans up resources. Should be called when you're done with the voice instance.
+
+Returns: `void`
+
+### getSpeakers()
+
+Returns a list of available voice speakers.
+
+Returns: `Promise<Array<{ voiceId: string; [key: string]: any }>>`
+
+### on()
+
+Registers an event listener for voice events.
+
+**event:** (`string`): Name of the event to listen for.
+
+**callback:** (`Function`): Function to call when the event occurs.
+
+Returns: `void`
+
+### off()
+
+Removes a previously registered event listener.
+
+**event:** (`string`): Name of the event to stop listening to.
+
+**callback:** (`Function`): The specific callback function to remove.
+
+Returns: `void`
+
+## Events
+
+The OpenAIRealtimeVoice class emits the following events:
+
+**speaking:** (`event`): Emitted when audio data is received from the model. Callback receives { audio: Int16Array }.
+
+**writing:** (`event`): Emitted when transcribed text is available. Callback receives { text: string, role: string }.
+
+**error:** (`event`): Emitted when an error occurs. Callback receives the error object.
+
+### OpenAI Realtime Events
+
+You can also listen to [OpenAI Realtime utility events](https://github.com/openai/openai-realtime-api-beta#reference-client-utility-events) by prefixing with 'openAIRealtime:':
+
+**openAIRealtime:conversation.created:** (`event`): Emitted when a new conversation is created.
+
+**openAIRealtime:conversation.interrupted:** (`event`): Emitted when a conversation is interrupted.
+
+**openAIRealtime:conversation.updated:** (`event`): Emitted when a conversation is updated.
+
+**openAIRealtime:conversation.item.appended:** (`event`): Emitted when an item is appended to the conversation.
+
+**openAIRealtime:conversation.item.completed:** (`event`): Emitted when an item in the conversation is completed.
+
+## Available Voices
+
+The following voice options are available:
+
+- `alloy`: Neutral and balanced
+- `ash`: Clear and precise
+- `ballad`: Melodic and smooth
+- `coral`: Warm and friendly
+- `echo`: Resonant and deep
+- `sage`: Calm and thoughtful
+- `shimmer`: Bright and energetic
+- `verse`: Versatile and expressive
+
+## Notes
+
+- API keys can be provided via constructor options or the `OPENAI_API_KEY` environment variable
+- The OpenAI Realtime Voice API uses WebSockets for real-time communication
+- Server-side Voice Activity Detection (VAD) provides better accuracy for speech detection
+- All audio data is processed as Int16Array format
+- The voice instance must be connected with `connect()` before using other methods
+- Always call `close()` when done to properly clean up resources
+- Memory management is handled by OpenAI Realtime API

package/.docs/reference/voice/openai.md

@@ -0,0 +1,88 @@
+# OpenAI
+
+The OpenAIVoice class in Mastra provides text-to-speech and speech-to-text capabilities using OpenAI's models.
+
+## Usage Example
+
+```typescript
+import { OpenAIVoice } from '@mastra/voice-openai'
+
+// Initialize with default configuration using environment variables
+const voice = new OpenAIVoice()
+
+// Or initialize with specific configuration
+const voiceWithConfig = new OpenAIVoice({
+  speechModel: {
+    name: 'tts-1-hd',
+    apiKey: 'your-openai-api-key',
+  },
+  listeningModel: {
+    name: 'whisper-1',
+    apiKey: 'your-openai-api-key',
+  },
+  speaker: 'alloy', // Default voice
+})
+
+// Convert text to speech
+const audioStream = await voice.speak('Hello, how can I help you?', {
+  speaker: 'nova', // Override default voice
+  speed: 1.2, // Adjust speech speed
+})
+
+// Convert speech to text
+const text = await voice.listen(audioStream, {
+  filetype: 'mp3',
+})
+```
+
+## Configuration
+
+### Constructor Options
+
+**speechModel?:** (`OpenAIConfig`): Configuration for text-to-speech synthesis. (Default: `{ name: 'tts-1' }`)
+
+**listeningModel?:** (`OpenAIConfig`): Configuration for speech-to-text recognition. (Default: `{ name: 'whisper-1' }`)
+
+**speaker?:** (`OpenAIVoiceId`): Default voice ID for speech synthesis. (Default: `'alloy'`)
+
+### OpenAIConfig
+
+**name?:** (`'tts-1' | 'tts-1-hd' | 'whisper-1'`): Model name. Use 'tts-1-hd' for higher quality audio.
+
+**apiKey?:** (`string`): OpenAI API key. Falls back to OPENAI\_API\_KEY environment variable.
+
+## Methods
+
+### speak()
+
+Converts text to speech using OpenAI's text-to-speech models.
+
+**input:** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
+
+**options.speaker?:** (`OpenAIVoiceId`): Voice ID to use for speech synthesis. (Default: `Constructor's speaker value`)
+
+**options.speed?:** (`number`): Speech speed multiplier. (Default: `1.0`)
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### listen()
+
+Transcribes audio using OpenAI's Whisper model.
+
+**audioStream:** (`NodeJS.ReadableStream`): Audio stream to transcribe.
+
+**options.filetype?:** (`string`): Audio format of the input stream. (Default: `'mp3'`)
+
+Returns: `Promise<string>`
+
+### getSpeakers()
+
+Returns an array of available voice options, where each node contains:
+
+**voiceId:** (`string`): Unique identifier for the voice
+
+## Notes
+
+- API keys can be provided via constructor options or the `OPENAI_API_KEY` environment variable
+- The `tts-1-hd` model provides higher quality audio but may have slower processing times
+- Speech recognition supports multiple audio formats including mp3, wav, and webm

package/.docs/reference/voice/playai.md

@@ -0,0 +1,80 @@
+# PlayAI
+
+The PlayAI voice implementation in Mastra provides text-to-speech capabilities using PlayAI's API.
+
+## Usage Example
+
+```typescript
+import { PlayAIVoice } from '@mastra/voice-playai'
+
+// Initialize with default configuration (uses PLAYAI_API_KEY environment variable and PLAYAI_USER_ID environment variable)
+const voice = new PlayAIVoice()
+
+// Initialize with default configuration
+const voice = new PlayAIVoice({
+  speechModel: {
+    name: 'PlayDialog',
+    apiKey: process.env.PLAYAI_API_KEY,
+    userId: process.env.PLAYAI_USER_ID,
+  },
+  speaker: 'Angelo', // Default voice
+})
+
+// Convert text to speech with a specific voice
+const audioStream = await voice.speak('Hello, world!', {
+  speaker:
+    's3://voice-cloning-zero-shot/b27bc13e-996f-4841-b584-4d35801aea98/original/manifest.json', // Dexter voice
+})
+```
+
+## Constructor Parameters
+
+**speechModel?:** (`PlayAIConfig`): Configuration for text-to-speech functionality (Default: `{ name: 'PlayDialog' }`)
+
+**speaker?:** (`string`): Default voice ID to use for speech synthesis (Default: `First available voice ID`)
+
+### PlayAIConfig
+
+**name?:** (`'PlayDialog' | 'Play3.0-mini'`): The PlayAI model to use (Default: `'PlayDialog'`)
+
+**apiKey?:** (`string`): PlayAI API key. Falls back to PLAYAI\_API\_KEY environment variable
+
+**userId?:** (`string`): PlayAI user ID. Falls back to PLAYAI\_USER\_ID environment variable
+
+## Methods
+
+### speak()
+
+Converts text to speech using the configured speech model and voice.
+
+**input:** (`string | NodeJS.ReadableStream`): Text to convert to speech. If a stream is provided, it will be converted to text first.
+
+**options.speaker?:** (`string`): Override the default speaker for this request (Default: `Constructor's speaker value`)
+
+Returns: `Promise<NodeJS.ReadableStream>`.
+
+### getSpeakers()
+
+Returns an array of available voice options, where each node contains:
+
+**name:** (`string`): Name of the voice
+
+**accent:** (`string`): Accent of the voice (e.g., 'US', 'British', 'Australian')
+
+**gender:** (`'M' | 'F'`): Gender of the voice
+
+**age:** (`'Young' | 'Middle' | 'Old'`): Age category of the voice
+
+**style:** (`'Conversational' | 'Narrative'`): Speaking style of the voice
+
+**voiceId:** (`string`): Unique identifier for the voice
+
+### listen()
+
+This method is not supported by PlayAI and will throw an error. PlayAI does not provide speech-to-text functionality.
+
+## Notes
+
+- PlayAI requires both an API key and a user ID for authentication
+- The service offers two models: 'PlayDialog' and 'Play3.0-mini'
+- Each voice has a unique S3 manifest ID that must be used when making API calls

package/.docs/reference/voice/sarvam.md

@@ -0,0 +1,126 @@
+# Sarvam
+
+The SarvamVoice class in Mastra provides text-to-speech and speech-to-text capabilities using Sarvam AI models.
+
+## Usage Example
+
+```typescript
+import { SarvamVoice } from '@mastra/voice-sarvam'
+
+// Initialize with default configuration using environment variables
+const voice = new SarvamVoice()
+
+// Or initialize with specific configuration
+const voiceWithConfig = new SarvamVoice({
+  speechModel: {
+    model: 'bulbul:v1',
+    apiKey: process.env.SARVAM_API_KEY!,
+    language: 'en-IN',
+    properties: {
+      pitch: 0,
+      pace: 1.65,
+      loudness: 1.5,
+      speech_sample_rate: 8000,
+      enable_preprocessing: false,
+      eng_interpolation_wt: 123,
+    },
+  },
+  listeningModel: {
+    model: 'saarika:v2',
+    apiKey: process.env.SARVAM_API_KEY!,
+    languageCode: 'en-IN',
+    filetype: 'wav',
+  },
+  speaker: 'meera', // Default voice
+})
+
+// Convert text to speech
+const audioStream = await voice.speak('Hello, how can I help you?')
+
+// Convert speech to text
+const text = await voice.listen(audioStream, {
+  filetype: 'wav',
+})
+```
+
+### Sarvam API Docs -
+
+<https://docs.sarvam.ai/api-reference-docs/endpoints/text-to-speech>
+
+## Configuration
+
+### Constructor Options
+
+**speechModel?:** (`SarvamVoiceConfig`): Configuration for text-to-speech synthesis. (Default: `{ model: 'bulbul:v1', language: 'en-IN' }`)
+
+**speaker?:** (`SarvamVoiceId`): The speaker to be used for the output audio. If not provided, Meera will be used as default. AvailableOptions - meera, pavithra, maitreyi, arvind, amol, amartya, diya, neel, misha, vian, arjun, maya (Default: `'meera'`)
+
+**listeningModel?:** (`SarvamListenOptions`): Configuration for speech-to-text recognition. (Default: `{ model: 'saarika:v2', language_code: 'unknown' }`)
+
+### SarvamVoiceConfig
+
+**apiKey?:** (`string`): Sarvam API key. Falls back to SARVAM\_API\_KEY environment variable.
+
+**model?:** (`SarvamTTSModel`): Specifies the model to use for text-to-speech conversion. (Default: `'bulbul:v1'`)
+
+**language:** (`SarvamTTSLanguage`): Target language for speech synthesis. Available options: hi-IN, bn-IN, kn-IN, ml-IN, mr-IN, od-IN, pa-IN, ta-IN, te-IN, en-IN, gu-IN (Default: `'en-IN'`)
+
+**properties?:** (`object`): Additional voice properties for customization.
+
+**properties.pitch?:** (`number`): Controls the pitch of the audio. Lower values result in a deeper voice, while higher values make it sharper. The suitable range is between -0.75 and 0.75.
+
+**properties.pace?:** (`number`): Controls the speed of the audio. Lower values result in slower speech, while higher values make it faster. The suitable range is between 0.5 and 2.0. Default is 1.0. Required range: 0.3 <= x <= 3
+
+**properties.loudness?:** (`number`): Controls the loudness of the audio. Lower values result in quieter audio, while higher values make it louder. The suitable range is between 0.3 and 3.0. Required range: 0 <= x <= 3
+
+**properties.speech\_sample\_rate?:** (`8000 | 16000 | 22050`): Audio sample rate in Hz.
+
+**properties.enable\_preprocessing?:** (`boolean`): Controls whether normalization of English words and numeric entities (e.g., numbers, dates) is performed. Set to true for better handling of mixed-language text. Default is false.
+
+**properties.eng\_interpolation\_wt?:** (`number`): Weight for interpolating with English speaker at encoder.
+
+### SarvamListenOptions
+
+**apiKey?:** (`string`): Sarvam API key. Falls back to SARVAM\_API\_KEY environment variable.
+
+**model?:** (`SarvamSTTModel`): Specifies the model to use for speech-to-text conversion. Note:- Default model is saarika:v2 . Available options: saarika:v1, saarika:v2, saarika:flash (Default: `'saarika:v2'`)
+
+**languageCode?:** (`SarvamSTTLanguage`): Specifies the language of the input audio. This parameter is required to ensure accurate transcription. For the saarika:v1 model, this parameter is mandatory. For the saarika:v2 model, it is optional. unknown: Use this when the language is not known; the API will detect it automatically. Note:- that the saarika:v1 model does not support unknown language code. Available options: unknown, hi-IN, bn-IN, kn-IN, ml-IN, mr-IN, od-IN, pa-IN, ta-IN, te-IN, en-IN, gu-IN (Default: `'unknown'`)
+
+**filetype?:** (`'mp3' | 'wav'`): Audio format of the input stream.
+
+## Methods
+
+### speak()
+
+Converts text to speech using Sarvam's text-to-speech models.
+
+**input:** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
+
+**options.speaker?:** (`SarvamVoiceId`): Voice ID to use for speech synthesis. (Default: `Constructor's speaker value`)
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### listen()
+
+Transcribes audio using Sarvam's speech recognition models.
+
+**input:** (`NodeJS.ReadableStream`): Audio stream to transcribe.
+
+**options?:** (`SarvamListenOptions`): Configuration options for speech recognition.
+
+Returns: `Promise<string>`
+
+### getSpeakers()
+
+Returns an array of available voice options.
+
+Returns: `Promise<Array<{voiceId: SarvamVoiceId}>>`
+
+## Notes
+
+- API key can be provided via constructor options or the `SARVAM_API_KEY` environment variable
+- If no API key is provided, the constructor will throw an error
+- The service communicates with the Sarvam AI API at `https://api.sarvam.ai`
+- Audio is returned as a stream containing binary audio data
+- Speech recognition supports mp3 and wav audio formats

package/.docs/reference/voice/speechify.md

@@ -0,0 +1,75 @@
+# Speechify
+
+The Speechify voice implementation in Mastra provides text-to-speech capabilities using Speechify's API.
+
+## Usage Example
+
+```typescript
+import { SpeechifyVoice } from '@mastra/voice-speechify'
+
+// Initialize with default configuration (uses SPEECHIFY_API_KEY environment variable)
+const voice = new SpeechifyVoice()
+
+// Initialize with custom configuration
+const voice = new SpeechifyVoice({
+  speechModel: {
+    name: 'simba-english',
+    apiKey: 'your-api-key',
+  },
+  speaker: 'george', // Default voice
+})
+
+// Convert text to speech
+const audioStream = await voice.speak('Hello, world!', {
+  speaker: 'henry', // Override default voice
+})
+```
+
+## Constructor Parameters
+
+**speechModel?:** (`SpeechifyConfig`): Configuration for text-to-speech functionality (Default: `{ name: 'simba-english' }`)
+
+**speaker?:** (`SpeechifyVoiceId`): Default voice ID to use for speech synthesis (Default: `'george'`)
+
+### SpeechifyConfig
+
+**name?:** (`VoiceModelName`): The Speechify model to use (Default: `'simba-english'`)
+
+**apiKey?:** (`string`): Speechify API key. Falls back to SPEECHIFY\_API\_KEY environment variable
+
+## Methods
+
+### speak()
+
+Converts text to speech using the configured speech model and voice.
+
+**input:** (`string | NodeJS.ReadableStream`): Text to convert to speech. If a stream is provided, it will be converted to text first.
+
+**options.speaker?:** (`string`): Override the default speaker for this request (Default: `Constructor's speaker value`)
+
+**options.model?:** (`VoiceModelName`): Override the default model for this request (Default: `Constructor's model value`)
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### getSpeakers()
+
+Returns an array of available voice options, where each node contains:
+
+**voiceId:** (`string`): Unique identifier for the voice
+
+**name:** (`string`): Display name of the voice
+
+**language:** (`string`): Language code for the voice
+
+**gender:** (`string`): Gender of the voice
+
+### listen()
+
+This method is not supported by Speechify and will throw an error. Speechify does not provide speech-to-text functionality.
+
+## Notes
+
+- Speechify requires an API key for authentication
+- The default model is 'simba-english'
+- Speech-to-text functionality is not supported
+- Additional audio stream options can be passed through the speak() method's options parameter

package/.docs/reference/voice/voice.addInstructions.md

@@ -0,0 +1,55 @@
+# voice.addInstructions()
+
+The `addInstructions()` method equips a voice provider with instructions that guide the model's behavior during real-time interactions. This is particularly useful for real-time voice providers that maintain context across a conversation.
+
+## Usage Example
+
+```typescript
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import { Agent } from '@mastra/core/agent'
+
+// Initialize a real-time voice provider
+const voice = new OpenAIRealtimeVoice({
+  realtimeConfig: {
+    model: 'gpt-5.1-realtime',
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+})
+
+// Create an agent with the voice provider
+const agent = new Agent({
+  name: 'Customer Support Agent',
+  instructions: 'You are a helpful customer support agent for a software company.',
+  model: 'openai/gpt-5.1',
+  voice,
+})
+
+// Add additional instructions to the voice provider
+voice.addInstructions(`
+  When speaking to customers:
+  - Always introduce yourself as the customer support agent
+  - Speak clearly and concisely
+  - Ask clarifying questions when needed
+  - Summarize the conversation at the end
+`)
+
+// Connect to the real-time service
+await voice.connect()
+```
+
+## Parameters
+
+**instructions:** (`string`): Instructions to guide the voice model's behavior
+
+## Return Value
+
+This method does not return a value.
+
+## Notes
+
+- Instructions are most effective when they are clear, specific, and relevant to the voice interaction
+- This method is primarily used with real-time voice providers that maintain conversation context
+- If called on a voice provider that doesn't support instructions, it will log a warning and do nothing
+- Instructions added with this method are typically combined with any instructions provided by an associated Agent
+- For best results, add instructions before starting a conversation (before calling `connect()`)
+- Multiple calls to `addInstructions()` may either replace or append to existing instructions, depending on the provider implementation

package/.docs/reference/voice/voice.addTools.md

@@ -0,0 +1,67 @@
+# voice.addTools()
+
+The `addTools()` method equips a voice provider with tools (functions) that can be called by the model during real-time interactions. This enables voice assistants to perform actions like searching for information, making calculations, or interacting with external systems.
+
+## Usage Example
+
+```typescript
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+// Define tools
+const weatherTool = createTool({
+  id: 'getWeather',
+  description: 'Get the current weather for a location',
+  inputSchema: z.object({
+    location: z.string().describe('The city and state, e.g. San Francisco, CA'),
+  }),
+  outputSchema: z.object({
+    message: z.string(),
+  }),
+  execute: async inputData => {
+    // Fetch weather data from an API
+    const response = await fetch(
+      `https://api.weather.com?location=${encodeURIComponent(inputData.location)}`,
+    )
+    const data = await response.json()
+    return {
+      message: `The current temperature in ${inputData.location} is ${data.temperature}°F with ${data.conditions}.`,
+    }
+  },
+})
+
+// Initialize a real-time voice provider
+const voice = new OpenAIRealtimeVoice({
+  realtimeConfig: {
+    model: 'gpt-5.1-realtime',
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+})
+
+// Add tools to the voice provider
+voice.addTools({
+  getWeather: weatherTool,
+})
+
+// Connect to the real-time service
+await voice.connect()
+```
+
+## Parameters
+
+**tools:** (`ToolsInput`): Object containing tool definitions that can be called by the voice model
+
+## Return Value
+
+This method does not return a value.
+
+## Notes
+
+- Tools must follow the Mastra tool format with name, description, input schema, and execute function
+- This method is primarily used with real-time voice providers that support function calling
+- If called on a voice provider that doesn't support tools, it will log a warning and do nothing
+- Tools added with this method are typically combined with any tools provided by an associated Agent
+- For best results, add tools before starting a conversation (before calling `connect()`)
+- The voice provider will automatically handle the invocation of tool handlers when the model decides to use them
+- Multiple calls to `addTools()` may either replace or merge with existing tools, depending on the provider implementation