## Quick Summary
The `tools` directory contains the complete set of built-in tools available to the agent. It follows a declarative, registry-based pattern where each tool module defines its functions and registers them with a central `tool_registry`. This allows for automatic discovery and dynamic availability of tools based on configuration and agent capabilities. The tools cover a wide range of functionalities including artifact management, audio/image processing, data analysis, web requests, and inter-agent communication.

## Files Overview
- `__init__.py`: Imports all tool modules, triggering their registration with the central registry.
- `audio_tools.py`: Provides tools for text-to-speech (TTS), multi-speaker TTS, audio concatenation, and transcription.
- `builtin_artifact_tools.py`: Contains core tools for creating, listing, loading, modifying, and deleting artifacts.
- `builtin_data_analysis_tools.py`: Offers tools for generating charts from Plotly configurations.
- `general_agent_tools.py`: Includes general-purpose utilities like file-to-markdown conversion and Mermaid diagram generation.
- `image_tools.py`: Provides tools for image generation, editing, and vision-based description of images and audio.
- `peer_agent_tool.py`: Defines the `PeerAgentTool` class for delegating tasks to other agents.
- `registry.py`: Implements the singleton `tool_registry` for managing all tool definitions.
- `test_tools.py`: Contains tools specifically for testing agent behavior, such as delays and failures.
- `tool_definition.py`: Defines the `BuiltinTool` Pydantic model used for declaring tools.
- `web_tools.py`: Contains a tool for making HTTP requests to external web resources.

## Developer API Reference

### __init__.py
**Purpose:** This file ensures that all built-in tool modules are imported when the `tools` package is loaded. This is crucial for the declarative tool registration pattern, as it triggers the `tool_registry.register()` calls within each tool module.
**Import:** `import src.solace_agent_mesh.agent.tools`

**Usage Examples:**
```python
# Importing the tools package is sufficient to register all built-in tools.
import src.solace_agent_mesh.agent.tools

# You can then access the registry to see all registered tools.
from src.solace_agent_mesh.agent.tools.registry import tool_registry
all_tools = tool_registry.get_all_tools()
print(f"Registered {len(all_tools)} tools.")
```

### audio_tools.py
**Purpose:** This file provides a collection of tools for audio processing, including text-to-speech (TTS) generation, audio concatenation, and transcription.
**Import:** `from src.solace_agent_mesh.agent.tools.audio_tools import select_voice, text_to_speech, multi_speaker_text_to_speech, concatenate_audio, transcribe_audio`

**Functions:**
- `select_voice(gender: Optional[str] = None, tone: Optional[str] = None, exclude_voices: Optional[List[str]] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Selects a suitable voice name based on criteria like gender and tone. Use this to get a consistent voice name that can be passed to the `text_to_speech` tool for multiple calls.
- `text_to_speech(text: str, output_filename: Optional[str] = None, voice_name: Optional[str] = None, gender: Optional[str] = None, tone: Optional[str] = None, language: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Converts text to speech using Gemini TTS API and saves as an MP3 artifact.
- `multi_speaker_text_to_speech(conversation_text: str, output_filename: Optional[str] = None, speaker_configs: Optional[List[Dict[str, str]]] = None, language: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Converts conversation text with speaker labels to speech using multiple voices.
- `concatenate_audio(clips_to_join: List[Dict[str, Any]], output_filename: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Combines multiple audio artifacts in a specified order into a single audio file, with optional pauses.
- `transcribe_audio(audio_filename: str, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Transcribes an audio recording using an OpenAI-compatible audio transcription API.

**Constants/Variables:**
- `ALL_AVAILABLE_VOICES: List[str]` - A list of all available voice names for TTS.
- `SUPPORTED_LANGUAGES: Dict[str, str]` - A mapping of common language names to their BCP-47 codes.
- `VOICE_TONE_MAPPING: Dict[str, List[str]]` - A dictionary mapping descriptive tones to lists of voice names.
- `GENDER_TO_VOICE_MAPPING: Dict[str, List[str]]` - A dictionary mapping genders ('male', 'female', 'neutral') to lists of voice names.

**Usage Examples:**
```python
# Assume 'tool_context' is a valid ToolContext object.

# 1. Generate a simple audio file
tts_result = await text_to_speech(
    text="Welcome to the developer guide.",
    output_filename="welcome.mp3",
    gender="female",
    tone="friendly",
    language="en-US",
    tool_context=tool_context
)
print(tts_result)

# 2. Generate a multi-speaker conversation
convo_result = await multi_speaker_text_to_speech(
    conversation_text="SpeakerA: How are you?\nSpeakerB: I am fine, thank you.",
    speaker_configs=[
        {"name": "SpeakerA", "gender": "male", "tone": "warm"},
        {"name": "SpeakerB", "gender": "female", "tone": "bright"}
    ],
    output_filename="dialogue.mp3",
    tool_context=tool_context
)
print(convo_result)

# 3. Concatenate the generated audio files
concat_result = await concatenate_audio(
    clips_to_join=[
        {"filename": "welcome.mp3:1", "pause_after_ms": 500},
        {"filename": "dialogue.mp3:1"}
    ],
    output_filename="combined_audio.mp3",
    tool_context=tool_context
)
print(concat_result)

# 4. Transcribe the combined audio
transcribe_result = await transcribe_audio(
    audio_filename="combined_audio.mp3:1",
    tool_context=tool_context
)
print(transcribe_result)
```

### builtin_artifact_tools.py
**Purpose:** This file provides the core tools for artifact management, allowing the agent to create, read, list, update, and delete data artifacts within the current session.
**Import:** `from src.solace_agent_mesh.agent.tools.builtin_artifact_tools import list_artifacts, load_artifact, signal_artifact_for_return, append_to_artifact, apply_embed_and_create_artifact, extract_content_from_artifact, delete_artifact`

**Functions:**
- `list_artifacts(tool_context: ToolContext = None) -> Dict[str, Any]` - Lists all available data artifact filenames and their versions for the current session.
- `load_artifact(filename: str, version: int, load_metadata_only: bool = False, max_content_length: Optional[int] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Loads the content or metadata of a specific artifact version.
- `signal_artifact_for_return(filename: str, version: int, tool_context: ToolContext = None