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

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

'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'],
]