neuron-tool-creator

name

neuron-tool-creator

description

Create custom tools, toolkits, and MCP integrations for Neuron AI agents. Use this skill when the user mentions creating tools, building toolkits, extending Tool class, defining tool properties, implementing tool execution, MCP server integration, Model Context Protocol, connecting external tools, or tool guidelines. Also trigger for any task involving ToolProperty, ArrayProperty, ObjectProperty, AbstractToolkit, McpConnector, or StdioTransport/SseHttpTransport/StreamableHttpTransport.

Neuron AI Tool Creator

This skill helps you create custom tools, toolkits, and MCP integrations for Neuron AI agents.

Core Concepts

Tools give agents the ability to:

• Execute actions (API calls, database queries, file operations)
• Retrieve information (web search, data lookup)
• Interact with external systems

Every tool has:

• Name: Unique identifier
• Description: Explains what the tool does (critical for LLM)
• Properties: Input parameters with types and descriptions
• Callable: The actual logic to run

Creating Custom Tools

Method 1: Extend Tool Class with __invoke

The cleanest approach for complex tools:

use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;

class WeatherTool extends Tool
{
    public function __construct()
    {
        parent::__construct(
            name: 'get_weather',
            description: 'Get the current weather for a location. Returns temperature, conditions, and humidity.'
        );
    }

    protected function properties(): array
    {
        return [
            ToolProperty::make(
                name: 'location',
                type: PropertyType::STRING,
                description: 'The city and country, e.g., "Paris, France"',
                required: true
            ),
            ToolProperty::make(
                name: 'units',
                type: PropertyType::STRING,
                description: 'Temperature units: "celsius" or "fahrenheit"',
                required: false,
                enum: ['celsius', 'fahrenheit']
            ),
        ];
    }

    public function __invoke(string $location, ?string $units = 'celsius'): string
    {
        // Your API call or logic here
        $weatherData = $this->fetchWeather($location, $units);

        return json_encode($weatherData);
    }

    private function fetchWeather(string $location, string $units): array
    {
        // Implementation...
        return [
            'location' => $location,
            'temperature' => 22,
            'units' => $units,
            'conditions' => 'sunny',
        ];
    }
}

Method 2: Fluent Builder with setCallable

For simpler tools or closures:

use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;

$weatherTool = Tool::make('get_weather', 'Get weather for a location')
    ->addProperty(
        ToolProperty::make(
            name: 'location',
            type: PropertyType::STRING,
            description: 'City name',
            required: true
        )
    )
    ->setCallable(function (string $location): string {
        // Your logic here
        return "Weather in {$location}: Sunny, 22°C";
    });

Method 3: Class with Dependencies

For tools that need external dependencies (database, API client):

use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;
use PDO;

class DatabaseQueryTool extends Tool
{
    public function __construct(protected PDO $pdo)
    {
        parent::__construct(
            name: 'query_users',
            description: 'Query user data from the database'
        );
    }

    protected function properties(): array
    {
        return [
            ToolProperty::make(
                name: 'email',
                type: PropertyType::STRING,
                description: 'User email to search for',
                required: false
            ),
            ToolProperty::make(
                name: 'limit',
                type: PropertyType::INTEGER,
                description: 'Maximum number of results',
                required: false
            ),
        ];
    }

    public function __invoke(?string $email = null, ?int $limit = 10): array
    {
        $query = "SELECT * FROM users";

        if ($email) {
            $query .= " WHERE email LIKE :email";
        }

        $query .= " LIMIT :limit";

        $stmt = $this->pdo->prepare($query);

        if ($email) {
            $stmt->bindValue(':email', "%{$email}%");
        }
        $stmt->bindValue(':limit', $limit, PDO::PARAM_INT);

        $stmt->execute();
        return $stmt->fetchAll(PDO::FETCH_ASSOC);
    }
}

Property Types

Basic Types

use NeuronAI\Tools\PropertyType;

PropertyType::STRING;   // Text values
PropertyType::INTEGER;  // Whole numbers
PropertyType::NUMBER;   // Floats/decimals
PropertyType::BOOLEAN;  // true/false
PropertyType::ARRAY;    // Lists
PropertyType::OBJECT;   // Key-value objects

ToolProperty (Scalar Values)

use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;

// Basic property
new ToolProperty(
    name: 'query',
    type: PropertyType::STRING,
    description: 'Search query',
    required: true
);

// Property with enum constraints
new ToolProperty(
    name: 'sort_order',
    type: PropertyType::STRING,
    description: 'Sort direction',
    required: false,
    enum: ['asc', 'desc']
);

// Integer with description
new ToolProperty(
    name: 'limit',
    type: PropertyType::INTEGER,
    description: 'Maximum results (1-100)',
    required: false
);

ArrayProperty (Lists)

use NeuronAI\Tools\ArrayProperty;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;

// Array of strings
new ArrayProperty(
    name: 'tags',
    description: 'List of tags to filter by',
    required: false,
    items: new ToolProperty(
        name: 'tag',
        type: PropertyType::STRING,
        description: 'Single tag'
    )
);

// Array with constraints
new ArrayProperty(
    name: 'ids',
    description: 'List of user IDs',
    required: true,
    items: new ToolProperty(
        name: 'id',
        type: PropertyType::INTEGER,
        description: 'User ID'
    ),
    minItems: 1,
    maxItems: 100
);

ObjectProperty (Complex Objects)

use NeuronAI\Tools\ObjectProperty;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;

// Inline object definition
new ObjectProperty(
    name: 'address',
    description: 'User address',
    required: true,
    properties: [
        new ToolProperty('street', PropertyType::STRING, 'Street name', true),
        new ToolProperty('city', PropertyType::STRING, 'City name', true),
        new ToolProperty('zip', PropertyType::STRING, 'Postal code', false),
    ]
);

// Object mapped to a PHP class (auto-deserialization)
new ObjectProperty(
    name: 'user',
    description: 'User object',
    required: true,
    class: User::class  // Auto-generates schema from class
);

Nested Complex Properties

// Array of objects
new ArrayProperty(
    name: 'contacts',
    description: 'List of contacts',
    required: true,
    items: new ObjectProperty(
        name: 'contact',
        properties: [
            new ToolProperty('name', PropertyType::STRING, 'Contact name', true),
            new ToolProperty('email', PropertyType::STRING, 'Email address', true),
        ]
    )
);

Tool Execution

Return Values

Tools must return a string or stringifiable value:

// String
public function __invoke(string $query): string
{
    return "Result: {$query}";
}

// Array (auto-converted to JSON)
public function __invoke(string $query): array
{
    return ['status' => 'success', 'data' => []];
}

// Object with __toString
public function __invoke(): Stringable
{
    return new class implements Stringable {
        public function __toString(): string {
            return 'result';
        }
    };
}

Accessing Inputs Directly

public function __invoke(string $query, ?string $filter = null): string
{
    // Access individual input
    $value = $this->getInput('query');

    // Access all inputs
    $allInputs = $this->getInputs();

    // Check if input exists
    if ($this->getInput('filter') !== null) {
        // ...
    }
}

Error Handling

public function __invoke(string $url): string
{
    try {
        $response = $this->httpClient->get($url);
        return (string) $response->getBody();
    } catch (\Exception $e) {
        // Return error message for the LLM to understand
        return "Error fetching URL: {$e->getMessage()}";
    }
}

Tool Visibility

Hidden tools are executable but not shown to the LLM:

// Visible to LLM (default)
$tool->visible(true);

// Hidden from LLM schema but still callable
$tool->visible(false);

Use case: Internal tools called by other tools, not directly by the agent.

Max Runs

Limit how many times a tool can be called in a single session:

$tool->setMaxRuns(5);  // Maximum 5 calls per session

Creating Toolkits

Toolkits group related tools together with shared context.

Basic Toolkit

use NeuronAI\Tools\Toolkits\AbstractToolkit;

class CalculatorToolkit extends AbstractToolkit
{
    public function guidelines(): ?string
    {
        return "This toolkit allows you to perform mathematical operations.
        You can use these functions to solve mathematical expressions
        step by step to calculate the final result.";
    }

    public function provide(): array
    {
        return [
            SumTool::make(),
            SubtractTool::make(),
            MultiplyTool::make(),
            DivideTool::make(),
        ];
    }
}

Toolkit with Dependencies

use NeuronAI\Tools\Toolkits\AbstractToolkit;
use PDO;

class MySQLToolkit extends AbstractToolkit
{
    public function __construct(protected PDO $pdo)
    {
    }

    public function guidelines(): ?string
    {
        return "These tools allow you to learn the database structure,
        getting detailed information about tables, columns, relationships,
        and constraints to generate and execute precise SQL queries.";
    }

    public function provide(): array
    {
        return [
            MySQLSchemaTool::make($this->pdo),
            MySQLSelectTool::make($this->pdo),
            MySQLWriteTool::make($this->pdo),
        ];
    }
}

Using Toolkits

use NeuronAI\Agent\Agent;

class MyAgent extends Agent
{
    protected function tools(): array
    {
        return [
            // Use full toolkit
            ...CalculatorToolkit::make(),

            // Use toolkit with dependencies
            ...MySQLToolkit::make($this->pdo),
        ];
    }
}

Toolkit Filtering

Control which tools are exposed:

// Exclude specific tools
...MySQLToolkit::make($pdo)
    ->exclude([MySQLWriteTool::class]),

// Include only specific tools
...MySQLToolkit::make($pdo)
    ->only([MySQLSchemaTool::class, MySQLSelectTool::class]),

// Configure tools dynamically
...MyToolkit::make()
    ->with(ExpensiveTool::class, function (Tool $tool): Tool {
        $tool->setMaxRuns(1);  // Limit expensive operations
        return $tool;
    }),

MCP (Model Context Protocol) Integration

MCP allows connecting to external tool servers.

Local MCP Server (Stdio)

use NeuronAI\MCP\McpConnector;

// Connect to local MCP server
$mcpTools = McpConnector::make([
    'command' => 'npx',
    'args' => ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir'],
])->tools();

HTTP MCP Server

use NeuronAI\MCP\McpConnector;

// Streamable HTTP (synchronous, recommended)
$mcpTools = McpConnector::make([
    'url' => 'https://mcp.example.com',
    'timeout' => 30,
])->tools();

// SSE HTTP (asynchronous)
$mcpTools = McpConnector::make([