Vizra ADK Tool Creation

# Building Vizra ADK Tools

Tools extend agent capabilities by allowing them to interact with databases, APIs, files, and external services.

## Tool Class Structure

Every tool MUST implement `ToolInterface`:

```php
<?php

namespace App\Tools;

use Vizra\VizraADK\Contracts\ToolInterface;
use Vizra\VizraADK\Agents\AgentContext;

class {{ ToolName }}Tool implements ToolInterface
{
    /**
     * Define the tool's schema for the LLM
     */
    public function definition(): array
    {
        return [
            'name' => '{{ tool_name }}',
            'description' => '{{ What this tool does - be specific }}',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'param1' => [
                        'type' => 'string',
                        'description' => '{{ Parameter description }}'
                    ],
                    'param2' => [
                        'type' => 'integer',
                        'description' => '{{ Parameter description }}'
                    ],
                ],
                'required' => ['param1'],
            ],
        ];
    }

    /**
     * Execute the tool with given arguments
     */
    public function execute(array $arguments, AgentContext $context): string
    {
        // Tool logic here

        return json_encode([
            'status' => 'success',
            'data' => $result
        ]);
    }
}
```

## Key Rules

1. **Naming Convention**:
   - Class name MUST end with `Tool`
   - The `name` in definition should be snake_case

2. **Definition Requirements**:
   - `name`: Unique identifier for the tool
   - `description`: Clear description of what the tool does (LLM uses this to decide when to use the tool)
   - `parameters`: JSON Schema format describing expected inputs

3. **Return Format**:
   - Always return JSON-encoded strings
   - Include status indicators for success/error
   - Provide meaningful error messages

## Parameter Types

```php
'parameters' => [
    'type' => 'object',
    'properties' => [
        // String parameter
        'name' => [
            'type' => 'string',
            'description' => 'The user name'
        ],

        // Integer parameter
        'count' => [
            'type' => 'integer',
            'description' => 'Number of items'
        ],

        // Boolean parameter
        'active' => [
            'type' => 'boolean',
            'description' => 'Whether the item is active'
        ],

        // Enum parameter
        'status' => [
            'type' => 'string',
            'enum' => ['pending', 'approved', 'rejected'],
            'description' => 'Current status'
        ],

        // Array parameter
        'tags' => [
            'type' => 'array',
            'items' => ['type' => 'string'],
            'description' => 'List of tags'
        ],

        // Object parameter
        'metadata' => [
            'type' => 'object',
            'properties' => [
                'key' => ['type' => 'string'],
                'value' => ['type' => 'string']
            ],
            'description' => 'Additional metadata'
        ],
    ],
    'required' => ['name', 'count'],
]
```

## Common Tool Patterns

### Database Query Tool
```php
class DatabaseQueryTool implements ToolInterface
{
    public function definition(): array
    {
        return [
            'name' => 'query_database',
            'description' => 'Execute a read-only database query to retrieve information',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'table' => [
                        'type' => 'string',
                        'description' => 'The table to query'
                    ],
                    'conditions' => [
                        'type' => 'object',
                        'description' => 'WHERE conditions as key-value pairs'
                    ],
                    'limit' => [
                        'type' => 'integer',
                        'description' => 'Maximum number of results'
                    ],
                ],
                'required' => ['table'],
            ],
        ];
    }

    public function execute(array $arguments, AgentContext $context): string
    {
        $allowedTables = ['users', 'orders', 'products'];

        if (!in_array($arguments['table'], $allowedTables)) {
            return json_encode([
                'status' => 'error',
                'message' => 'Table not allowed'
            ]);
        }

        $query = DB::table($arguments['table']);

        if (isset($arguments['conditions'])) {
            foreach ($arguments['conditions'] as $key => $value) {
                $query->where($key, $value);
            }
        }

        $results = $query->limit($arguments['limit'] ?? 10)->get();

        return json_encode([
            'status' => 'success',
            'data' => $results,
            'count' => $results->count()
        ]);
    }
}
```

### API Integration Tool
```php
class ExternalApiTool implements ToolInterface
{
    public function definition(): array
    {
        return [
            'name' => 'call_external_api',
            'description' => 'Make requests to the external service API',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'endpoint' => [
                        'type' => 'string',
                        'description' => 'API endpoint path'
                    ],
                    'method' => [
                        'type' => 'string',
                        'enum' => ['GET', 'POST'],
                        'description' => 'HTTP method'
                    ],
                    'data' => [
                        'type' => 'object',
                        'description' => 'Request payload for POST requests'
                    ],
                ],
                'required' => [